diff --git a/en/resources/beta/index.md b/en/resources/beta/index.md index df98f42a..5680a0e6 100644 --- a/en/resources/beta/index.md +++ b/en/resources/beta/index.md @@ -1,21401 +1,23293 @@ # Beta -# ChatKit - -## Domain Types +# Responses -### ChatKit Workflow +## Create a model response -- `ChatKitWorkflow object { id, state_variables, tracing, version }` +**post** `/responses?beta=true` - Workflow metadata and state returned for the session. +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. - - `id: string` +### Header Parameters - Identifier of the workflow backing the session. +- `"openai-beta": optional array of "responses_multi_agent=v1"` - - `state_variables: map[string or boolean or number]` + - `"responses_multi_agent=v1"` - State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided. +### Body Parameters - - `string` +- `background: optional boolean` - - `boolean` + Whether to run the model response in the background. + [Learn more](/docs/guides/background). - - `number` +- `context_management: optional array of object { type, compact_threshold }` - - `tracing: object { enabled }` + Context management configuration for this request. - Tracing settings applied to the workflow. + - `type: string` - - `enabled: boolean` + The context management entry type. Currently only 'compaction' is supported. - Indicates whether tracing is enabled. + - `compact_threshold: optional number` - - `version: string` + Token threshold at which compaction should be triggered for this entry. - Specific workflow version used for the session. Defaults to null when using the latest deployment. +- `conversation: optional string or BetaResponseConversationParam` -# Sessions + 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. -## Cancel chat session + - `ConversationID = string` -**post** `/chatkit/sessions/{session_id}/cancel` + The unique ID of the conversation. -Cancel chat session + - `BetaResponseConversationParam object { id }` -### Path Parameters + The conversation that this response belongs to. -- `session_id: string` + - `id: string` -### Returns + The unique ID of the conversation. -- `ChatSession object { id, chatkit_configuration, client_secret, 7 more }` +- `include: optional array of BetaResponseIncludable` - Represents a ChatKit session and its resolved configuration. + Specify additional output data to include in the model response. Currently supported values are: - - `id: string` + - `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). - Identifier for the ChatKit session. + - `"file_search_call.results"` - - `chatkit_configuration: ChatSessionChatKitConfiguration` + - `"web_search_call.results"` - Resolved ChatKit feature configuration for the session. + - `"web_search_call.action.sources"` - - `automatic_thread_titling: ChatSessionAutomaticThreadTitling` + - `"message.input_image.image_url"` - Automatic thread titling preferences. + - `"computer_call_output.output.image_url"` - - `enabled: boolean` + - `"code_interpreter_call.outputs"` - Whether automatic thread titling is enabled. + - `"reasoning.encrypted_content"` - - `file_upload: ChatSessionFileUpload` + - `"message.output_text.logprobs"` - Upload settings for the session. +- `input: optional string or array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` - - `enabled: boolean` + Text, image, or file inputs to the model, used to generate a response. - Indicates if uploads are enabled for the session. + Learn more: - - `max_file_size: number` + - [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) - Maximum upload size in megabytes. + - `TextInput = string` - - `max_files: number` + A text input to the model, equivalent to a text input with the + `user` role. - Maximum number of uploads allowed during the session. + - `InputItemList = array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` - - `history: ChatSessionHistory` + A list of one or many input items to the model, containing + different content types. - History retention configuration. + - `BetaEasyInputMessage object { content, role, phase, type }` - - `enabled: 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. - Indicates if chat history is persisted for the session. + - `content: string or BetaResponseInputMessageContentList` - - `recent_threads: number` + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - Number of prior threads surfaced in history views. Defaults to null when all history is retained. + - `TextInput = string` - - `client_secret: string` + A text input to the model. - Ephemeral client secret that authenticates session requests. + - `BetaResponseInputMessageContentList = array of BetaResponseInputContent` - - `expires_at: number` + A list of one or many input items to the model, containing different content + types. - Unix timestamp (in seconds) for when the session expires. + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `max_requests_per_1_minute: number` + A text input to the model. - Convenience copy of the per-minute request limit. + - `text: string` - - `object: "chatkit.session"` + The text input to the model. - Type discriminator that is always `chatkit.session`. + - `type: "input_text"` - - `"chatkit.session"` + The type of the input item. Always `input_text`. - - `rate_limits: ChatSessionRateLimits` + - `"input_text"` - Resolved rate limit values. + - `prompt_cache_breakpoint: optional object { mode }` - - `max_requests_per_1_minute: 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. - Maximum allowed requests per one-minute window. + - `mode: "explicit"` - - `status: ChatSessionStatus` + The breakpoint mode. Always `explicit`. - Current lifecycle state of the session. + - `"explicit"` - - `"active"` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `"expired"` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `"cancelled"` + - `detail: "low" or "high" or "auto" or "original"` - - `user: string` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - User identifier associated with the session. + - `"low"` - - `workflow: ChatKitWorkflow` + - `"high"` - Workflow metadata for the session. + - `"auto"` - - `id: string` + - `"original"` - Identifier of the workflow backing the session. + - `type: "input_image"` - - `state_variables: map[string or boolean or number]` + The type of the input item. Always `input_image`. - State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided. + - `"input_image"` - - `string` + - `file_id: optional string` - - `boolean` + The ID of the file to be sent to the model. - - `number` + - `image_url: optional string` - - `tracing: object { enabled }` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - Tracing settings applied to the workflow. + - `prompt_cache_breakpoint: optional object { mode }` - - `enabled: boolean` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - Indicates whether tracing is enabled. + - `mode: "explicit"` - - `version: string` + The breakpoint mode. Always `explicit`. - Specific workflow version used for the session. Defaults to null when using the latest deployment. + - `"explicit"` -### Example + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` -```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" -``` + A file input to the model. -#### Response + - `type: "input_file"` -```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 the input item. Always `input_file`. -### Example + - `"input_file"` -```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" -``` + - `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 -{ - "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 -} -``` + - `"auto"` -## Create ChatKit session + - `"low"` -**post** `/chatkit/sessions` + - `"high"` -Create ChatKit session + - `file_data: optional string` -### Body Parameters + The content of the file to be sent to the model. -- `user: string` + - `file_id: optional string` - A free-form string that identifies your end user; ensures this Session can access other objects that have the same `user` scope. + The ID of the file to be sent to the model. -- `workflow: ChatSessionWorkflowParam` + - `file_url: optional string` - Workflow that powers the session. + The URL of the file to be sent to the model. - - `id: string` + - `filename: optional string` - Identifier for the workflow invoked by the session. + The name of the file to be sent to the model. - - `state_variables: optional map[string or boolean or number]` + - `prompt_cache_breakpoint: optional object { mode }` - 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. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `string` + - `mode: "explicit"` - - `boolean` + The breakpoint mode. Always `explicit`. - - `number` + - `"explicit"` - - `tracing: optional object { enabled }` + - `role: "user" or "assistant" or "system" or "developer"` - Optional tracing overrides for the workflow invocation. When omitted, tracing is enabled by default. + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - - `enabled: optional boolean` + - `"user"` - Whether tracing is enabled during the session. Defaults to true. + - `"assistant"` - - `version: optional string` + - `"system"` - Specific workflow version to run. Defaults to the latest deployed version. + - `"developer"` -- `chatkit_configuration: optional ChatSessionChatKitConfigurationParam` + - `phase: optional "commentary" or "final_answer"` - Optional overrides for ChatKit runtime configuration features + 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. - - `automatic_thread_titling: optional object { enabled }` + - `"commentary"` - Configuration for automatic thread titling. When omitted, automatic thread titling is enabled by default. + - `"final_answer"` - - `enabled: optional boolean` + - `type: optional "message"` - Enable automatic thread title generation. Defaults to true. + The type of the message input. Always `message`. - - `file_upload: optional object { enabled, max_file_size, max_files }` + - `"message"` - Configuration for upload enablement and limits. When omitted, uploads are disabled by default (max_files 10, max_file_size 512 MB). + - `Message object { content, role, agent, 2 more }` - - `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. - Enable uploads for this session. Defaults to false. + - `content: BetaResponseInputMessageContentList` - - `max_file_size: optional number` + A list of one or many input items to the model, containing different content + types. - Maximum size in megabytes for each uploaded file. Defaults to 512 MB, which is the maximum allowable size. + - `role: "user" or "system" or "developer"` - - `max_files: optional number` + The role of the message input. One of `user`, `system`, or `developer`. - Maximum number of files that can be uploaded to the session. Defaults to 10. + - `"user"` - - `history: optional object { enabled, recent_threads }` + - `"system"` - Configuration for chat history retention. When omitted, history is enabled by default with no limit on recent_threads (null). + - `"developer"` - - `enabled: optional boolean` + - `agent: optional object { agent_name }` - Enables chat users to access previous ChatKit threads. Defaults to true. + The agent that produced this item. - - `recent_threads: optional number` + - `agent_name: string` - Number of recent ChatKit threads users have access to. Defaults to unlimited when unset. + The canonical name of the agent that produced this item. -- `expires_after: optional ChatSessionExpiresAfterParam` + - `status: optional "in_progress" or "completed" or "incomplete"` - Optional override for session expiration timing in seconds from creation. Defaults to 10 minutes. + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `anchor: "created_at"` + - `"in_progress"` - Base timestamp used to calculate expiration. Currently fixed to `created_at`. + - `"completed"` - - `"created_at"` + - `"incomplete"` - - `seconds: number` + - `type: optional "message"` - Number of seconds after the anchor when the session expires. + The type of the message input. Always set to `message`. -- `rate_limits: optional ChatSessionRateLimitsParam` + - `"message"` - Optional override for per-minute request limits. When omitted, defaults to 10. + - `BetaResponseOutputMessage object { id, content, role, 4 more }` - - `max_requests_per_1_minute: optional number` + An output message from the model. - Maximum number of requests allowed per minute for the session. Defaults to 10. + - `id: string` -### Returns + The unique ID of the output message. -- `ChatSession object { id, chatkit_configuration, client_secret, 7 more }` + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - Represents a ChatKit session and its resolved configuration. + The content of the output message. - - `id: string` + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - Identifier for the ChatKit session. + A text output from the model. - - `chatkit_configuration: ChatSessionChatKitConfiguration` + - `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 }` - Resolved ChatKit feature configuration for the session. + The annotations of the text output. - - `automatic_thread_titling: ChatSessionAutomaticThreadTitling` + - `FileCitation object { file_id, filename, index, type }` - Automatic thread titling preferences. + A citation to a file. - - `enabled: boolean` + - `file_id: string` - Whether automatic thread titling is enabled. + The ID of the file. - - `file_upload: ChatSessionFileUpload` + - `filename: string` - Upload settings for the session. + The filename of the file cited. - - `enabled: boolean` + - `index: number` - Indicates if uploads are enabled for the session. + The index of the file in the list of files. - - `max_file_size: number` + - `type: "file_citation"` - Maximum upload size in megabytes. + The type of the file citation. Always `file_citation`. - - `max_files: number` + - `"file_citation"` - Maximum number of uploads allowed during the session. + - `URLCitation object { end_index, start_index, title, 2 more }` - - `history: ChatSessionHistory` + A citation for a web resource used to generate a model response. - History retention configuration. + - `end_index: number` - - `enabled: boolean` + The index of the last character of the URL citation in the message. - Indicates if chat history is persisted for the session. + - `start_index: number` - - `recent_threads: number` + The index of the first character of the URL citation in the message. - Number of prior threads surfaced in history views. Defaults to null when all history is retained. + - `title: string` - - `client_secret: string` + The title of the web resource. - Ephemeral client secret that authenticates session requests. + - `type: "url_citation"` - - `expires_at: number` + The type of the URL citation. Always `url_citation`. - Unix timestamp (in seconds) for when the session expires. + - `"url_citation"` - - `max_requests_per_1_minute: number` + - `url: string` - Convenience copy of the per-minute request limit. + The URL of the web resource. - - `object: "chatkit.session"` + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - Type discriminator that is always `chatkit.session`. + A citation for a container file used to generate a model response. - - `"chatkit.session"` + - `container_id: string` - - `rate_limits: ChatSessionRateLimits` + The ID of the container file. - Resolved rate limit values. + - `end_index: number` - - `max_requests_per_1_minute: number` + The index of the last character of the container file citation in the message. - Maximum allowed requests per one-minute window. + - `file_id: string` - - `status: ChatSessionStatus` + The ID of the file. - Current lifecycle state of the session. + - `filename: string` - - `"active"` + The filename of the container file cited. - - `"expired"` + - `start_index: number` - - `"cancelled"` + The index of the first character of the container file citation in the message. - - `user: string` + - `type: "container_file_citation"` - User identifier associated with the session. + The type of the container file citation. Always `container_file_citation`. - - `workflow: ChatKitWorkflow` + - `"container_file_citation"` - Workflow metadata for the session. + - `FilePath object { file_id, index, type }` - - `id: string` + A path to a file. - Identifier of the workflow backing the session. + - `file_id: string` - - `state_variables: map[string or boolean or number]` + The ID of the file. - State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided. + - `index: number` - - `string` + The index of the file in the list of files. - - `boolean` + - `type: "file_path"` - - `number` + The type of the file path. Always `file_path`. - - `tracing: object { enabled }` + - `"file_path"` - Tracing settings applied to the workflow. + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - - `enabled: boolean` + - `token: string` - Indicates whether tracing is enabled. + - `bytes: array of number` - - `version: string` + - `logprob: number` - Specific workflow version used for the session. Defaults to null when using the latest deployment. + - `top_logprobs: array of object { token, bytes, logprob }` -### Example + - `token: string` -```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" - } - }' -``` + - `bytes: array of number` -#### Response + - `logprob: number` -```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" - } -} -``` + - `text: string` -### Example + The text output from the model. -```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: "output_text"` -#### Response + The type of the output text. Always `output_text`. -```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" -} -``` + - `"output_text"` -# Threads + - `BetaResponseOutputRefusal object { refusal, type }` -## List ChatKit thread items + A refusal from the model. -**get** `/chatkit/threads/{thread_id}/items` + - `refusal: string` -List ChatKit thread items + The refusal explanation from the model. -### Path Parameters + - `type: "refusal"` -- `thread_id: string` + The type of the refusal. Always `refusal`. -### Query Parameters + - `"refusal"` -- `after: optional string` + - `role: "assistant"` - List items created after this thread item ID. Defaults to null for the first page. + The role of the output message. Always `assistant`. -- `before: optional string` + - `"assistant"` - List items created before this thread item ID. Defaults to null for the newest results. + - `status: "in_progress" or "completed" or "incomplete"` -- `limit: optional number` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - Maximum number of thread items to return. Defaults to 20. + - `"in_progress"` -- `order: optional "asc" or "desc"` + - `"completed"` - Sort order for results by creation time. Defaults to `desc`. + - `"incomplete"` - - `"asc"` + - `type: "message"` - - `"desc"` + The type of the output message. Always `message`. -### Returns + - `"message"` -- `ChatKitThreadItemList object { data, first_id, has_more, 2 more }` + - `agent: optional object { agent_name }` - A paginated list of thread items rendered for the ChatKit API. + The agent that produced this item. - - `data: array of ChatKitThreadUserMessageItem or ChatKitThreadAssistantMessageItem or ChatKitWidgetItem or 3 more` + - `agent_name: string` - A list of items + The canonical name of the agent that produced this item. - - `ChatKitThreadUserMessageItem object { id, attachments, content, 5 more }` + - `phase: optional "commentary" or "final_answer"` - User-authored messages within a thread. + 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 of the thread item. + - `"final_answer"` - - `attachments: array of ChatKitAttachment` + - `FileSearchCall object { id, queries, status, 3 more }` - Attachments associated with the user message. Defaults to an empty list. + The results of a file search tool call. See the + [file search guide](/docs/guides/tools-file-search) for more information. - `id: string` - Identifier for the attachment. - - - `mime_type: string` + The unique ID of the file search tool call. - MIME type of the attachment. + - `queries: array of string` - - `name: string` + The queries used to search for files. - Original display name for the attachment. + - `status: "in_progress" or "searching" or "completed" or 2 more` - - `preview_url: string` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - Preview URL for rendering the attachment inline. + - `"in_progress"` - - `type: "image" or "file"` + - `"searching"` - Attachment discriminator. + - `"completed"` - - `"image"` + - `"incomplete"` - - `"file"` + - `"failed"` - - `content: array of object { text, type } or object { text, type }` + - `type: "file_search_call"` - Ordered content elements supplied by the user. + The type of the file search tool call. Always `file_search_call`. - - `InputText object { text, type }` + - `"file_search_call"` - Text block that a user contributed to the thread. + - `agent: optional object { agent_name }` - - `text: string` + The agent that produced this item. - Plain-text content supplied by the user. + - `agent_name: string` - - `type: "input_text"` + The canonical name of the agent that produced this item. - Type discriminator that is always `input_text`. + - `results: optional array of object { attributes, file_id, filename, 2 more }` - - `"input_text"` + The results of the file search tool call. - - `QuotedText object { text, type }` + - `attributes: optional map[string or number or boolean]` - Quoted snippet that the user referenced in their 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. Keys are strings + with a maximum length of 64 characters. Values are strings with a maximum + length of 512 characters, booleans, or numbers. - - `text: string` + - `string` - Quoted text content. + - `number` - - `type: "quoted_text"` + - `boolean` - Type discriminator that is always `quoted_text`. + - `file_id: optional string` - - `"quoted_text"` + The unique ID of the file. - - `created_at: number` + - `filename: optional string` - Unix timestamp (in seconds) for when the item was created. + The name of the file. - - `inference_options: object { model, tool_choice }` + - `score: optional number` - Inference overrides applied to the message. Defaults to null when unset. + The relevance score of the file - a value between 0 and 1. - - `model: string` + - `text: optional string` - Model name that generated the response. Defaults to null when using the session default. + The text that was retrieved from the file. - - `tool_choice: object { id }` + - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` - Preferred tool to invoke. Defaults to null when ChatKit should auto-select. + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - `id: string` - Identifier of the requested tool. + The unique ID of the computer call. - - `object: "chatkit.thread_item"` + - `call_id: string` - Type discriminator that is always `chatkit.thread_item`. + An identifier used when responding to the tool call with output. - - `"chatkit.thread_item"` + - `pending_safety_checks: array of object { id, code, message }` - - `thread_id: string` + The pending safety checks for the computer call. - Identifier of the parent thread. + - `id: string` - - `type: "chatkit.user_message"` + The ID of the pending safety check. - - `"chatkit.user_message"` + - `code: optional string` - - `ChatKitThreadAssistantMessageItem object { id, content, created_at, 3 more }` + The type of the pending safety check. - Assistant-authored message within a thread. + - `message: optional string` - - `id: string` + Details about the pending safety check. - Identifier of the thread item. + - `status: "in_progress" or "completed" or "incomplete"` - - `content: array of ChatKitResponseOutputText` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Ordered assistant response segments. + - `"in_progress"` - - `annotations: array of object { source, type } or object { source, type }` + - `"completed"` - Ordered list of annotations attached to the response text. + - `"incomplete"` - - `File object { source, type }` + - `type: "computer_call"` - Annotation that references an uploaded file. + The type of the computer call. Always `computer_call`. - - `source: object { filename, type }` + - `"computer_call"` - File attachment referenced by the annotation. + - `action: optional BetaComputerAction` - - `filename: string` + A click action. - Filename referenced by the annotation. + - `Click object { button, type, x, 2 more }` - - `type: "file"` + A click action. - Type discriminator that is always `file`. + - `button: "left" or "right" or "wheel" or 2 more` - - `"file"` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `type: "file"` + - `"left"` - Type discriminator that is always `file` for this annotation. + - `"right"` - - `"file"` + - `"wheel"` - - `URL object { source, type }` + - `"back"` - Annotation that references a URL. + - `"forward"` - - `source: object { type, url }` + - `type: "click"` - URL referenced by the annotation. + Specifies the event type. For a click action, this property is always `click`. - - `type: "url"` + - `"click"` - Type discriminator that is always `url`. + - `x: number` - - `"url"` + The x-coordinate where the click occurred. - - `url: string` + - `y: number` - URL referenced by the annotation. + The y-coordinate where the click occurred. - - `type: "url"` + - `keys: optional array of string` - Type discriminator that is always `url` for this annotation. + The keys being held while clicking. - - `"url"` + - `DoubleClick object { keys, type, x, y }` - - `text: string` + A double click action. - Assistant generated text. + - `keys: array of string` - - `type: "output_text"` + The keys being held while double-clicking. - Type discriminator that is always `output_text`. + - `type: "double_click"` - - `"output_text"` + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `created_at: number` + - `"double_click"` - Unix timestamp (in seconds) for when the item was created. + - `x: number` - - `object: "chatkit.thread_item"` + The x-coordinate where the double click occurred. - Type discriminator that is always `chatkit.thread_item`. + - `y: number` - - `"chatkit.thread_item"` + The y-coordinate where the double click occurred. - - `thread_id: string` + - `Drag object { path, type, keys }` - Identifier of the parent thread. + A drag action. - - `type: "chatkit.assistant_message"` + - `path: array of object { x, y }` - Type discriminator that is always `chatkit.assistant_message`. + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `"chatkit.assistant_message"` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `ChatKitWidgetItem object { id, created_at, object, 3 more }` + - `x: number` - Thread item that renders a widget payload. + The x-coordinate. - - `id: string` + - `y: number` - Identifier of the thread item. + The y-coordinate. - - `created_at: number` + - `type: "drag"` - Unix timestamp (in seconds) for when the item was created. + Specifies the event type. For a drag action, this property is always set to `drag`. - - `object: "chatkit.thread_item"` + - `"drag"` - Type discriminator that is always `chatkit.thread_item`. + - `keys: optional array of string` - - `"chatkit.thread_item"` + The keys being held while dragging the mouse. - - `thread_id: string` + - `Keypress object { keys, type }` - Identifier of the parent thread. + A collection of keypresses the model would like to perform. - - `type: "chatkit.widget"` + - `keys: array of string` - Type discriminator that is always `chatkit.widget`. + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `"chatkit.widget"` + - `type: "keypress"` - - `widget: string` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - Serialized widget payload rendered in the UI. + - `"keypress"` - - `ChatKitClientToolCall object { id, arguments, call_id, 7 more }` + - `Move object { type, x, y, keys }` - Record of a client side tool invocation initiated by the assistant. + 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`. - - `arguments: string` + - `"move"` - JSON-encoded arguments that were sent to the tool. + - `x: number` - - `call_id: string` + The x-coordinate to move to. - Identifier for the client tool call. + - `y: number` - - `created_at: number` + The y-coordinate to move to. - Unix timestamp (in seconds) for when the item was created. + - `keys: optional array of string` - - `name: string` + The keys being held while moving the mouse. - Tool name that was invoked. + - `Screenshot object { type }` - - `object: "chatkit.thread_item"` + A screenshot action. - Type discriminator that is always `chatkit.thread_item`. + - `type: "screenshot"` - - `"chatkit.thread_item"` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `output: string` + - `"screenshot"` - JSON-encoded output captured from the tool. Defaults to null while execution is in progress. + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - - `status: "in_progress" or "completed"` + A scroll action. - Execution status for the tool call. + - `scroll_x: number` - - `"in_progress"` + The horizontal scroll distance. - - `"completed"` + - `scroll_y: number` - - `thread_id: string` + The vertical scroll distance. - Identifier of the parent thread. + - `type: "scroll"` - - `type: "chatkit.client_tool_call"` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - Type discriminator that is always `chatkit.client_tool_call`. + - `"scroll"` - - `"chatkit.client_tool_call"` + - `x: number` - - `ChatKitTask object { id, created_at, heading, 5 more }` + The x-coordinate where the scroll occurred. - Task emitted by the workflow to show progress and status updates. + - `y: number` - - `id: string` + The y-coordinate where the scroll occurred. - Identifier of the thread item. + - `keys: optional array of string` - - `created_at: number` + The keys being held while scrolling. - Unix timestamp (in seconds) for when the item was created. + - `Type object { text, type }` - - `heading: string` + An action to type in text. - Optional heading for the task. Defaults to null when not provided. + - `text: string` - - `object: "chatkit.thread_item"` + The text to type. - Type discriminator that is always `chatkit.thread_item`. + - `type: "type"` - - `"chatkit.thread_item"` + Specifies the event type. For a type action, this property is always set to `type`. - - `summary: string` + - `"type"` - Optional summary that describes the task. Defaults to null when omitted. + - `Wait object { type }` - - `task_type: "custom" or "thought"` + A wait action. - Subtype for the task. + - `type: "wait"` - - `"custom"` + Specifies the event type. For a wait action, this property is always set to `wait`. - - `"thought"` + - `"wait"` - - `thread_id: string` + - `actions: optional BetaComputerActionList` - Identifier of the parent thread. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `type: "chatkit.task"` + - `Click object { button, type, x, 2 more }` - Type discriminator that is always `chatkit.task`. + A click action. - - `"chatkit.task"` + - `DoubleClick object { keys, type, x, y }` - - `ChatKitTaskGroup object { id, created_at, object, 3 more }` + A double click action. - Collection of workflow tasks grouped together in the thread. + - `Drag object { path, type, keys }` - - `id: string` + A drag action. - Identifier of the thread item. + - `Keypress object { keys, type }` - - `created_at: number` + A collection of keypresses the model would like to perform. - Unix timestamp (in seconds) for when the item was created. + - `Move object { type, x, y, keys }` - - `object: "chatkit.thread_item"` + A mouse move action. - Type discriminator that is always `chatkit.thread_item`. + - `Screenshot object { type }` - - `"chatkit.thread_item"` + A screenshot action. - - `tasks: array of object { heading, summary, type }` + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - Tasks included in the group. + A scroll action. - - `heading: string` + - `Type object { text, type }` - Optional heading for the grouped task. Defaults to null when not provided. + An action to type in text. - - `summary: string` + - `Wait object { type }` - Optional summary that describes the grouped task. Defaults to null when omitted. + A wait action. - - `type: "custom" or "thought"` + - `agent: optional object { agent_name }` - Subtype for the grouped task. + The agent that produced this item. - - `"custom"` + - `agent_name: string` - - `"thought"` + The canonical name of the agent that produced this item. - - `thread_id: string` + - `ComputerCallOutput object { call_id, output, type, 4 more }` - Identifier of the parent thread. + The output of a computer tool call. - - `type: "chatkit.task_group"` + - `call_id: string` - Type discriminator that is always `chatkit.task_group`. + The ID of the computer tool call that produced the output. - - `"chatkit.task_group"` + - `output: BetaResponseComputerToolCallOutputScreenshot` - - `first_id: string` + A computer screenshot image used with the computer use tool. - The ID of the first item in the list. + - `type: "computer_screenshot"` - - `has_more: boolean` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - Whether there are more items available. + - `"computer_screenshot"` - - `last_id: string` + - `file_id: optional string` - The ID of the last item in the list. + The identifier of an uploaded file that contains the screenshot. - - `object: "list"` + - `image_url: optional string` - The type of object returned, must be `list`. + The URL of the screenshot image. - - `"list"` + - `type: "computer_call_output"` -### Example + The type of the computer tool call output. Always `computer_call_output`. -```http -curl https://api.openai.com/v1/chatkit/threads/$THREAD_ID/items \ - -H 'OpenAI-Beta: chatkit_beta=v1' \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + - `"computer_call_output"` -#### Response + - `id: optional string` -```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 ID of the computer tool call output. -### Example + - `acknowledged_safety_checks: optional array of object { id, code, message }` -```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" -``` + The safety checks reported by the API that have been acknowledged by the developer. -#### Response + - `id: string` -```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" -} -``` + The ID of the pending safety check. -## Retrieve ChatKit thread + - `code: optional string` -**get** `/chatkit/threads/{thread_id}` + The type of the pending safety check. -Retrieve ChatKit thread + - `message: optional string` -### Path Parameters + Details about the pending safety check. -- `thread_id: string` + - `agent: optional object { agent_name }` -### Returns + The agent that produced this item. -- `ChatKitThread object { id, created_at, object, 3 more }` + - `agent_name: string` - Represents a ChatKit thread and its current status. + The canonical name of the agent that produced this item. - - `id: string` + - `status: optional "in_progress" or "completed" or "incomplete"` - Identifier of the thread. + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - - `created_at: number` + - `"in_progress"` - Unix timestamp (in seconds) for when the thread was created. + - `"completed"` - - `object: "chatkit.thread"` + - `"incomplete"` - Type discriminator that is always `chatkit.thread`. + - `WebSearchCall object { id, action, status, 2 more }` - - `"chatkit.thread"` + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. - - `status: object { type } or object { reason, type } or object { reason, type }` + - `id: string` - Current status for the thread. Defaults to `active` for newly created threads. + The unique ID of the web search tool call. - - `Active object { type }` + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - Indicates that a thread is active. + 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: "active"` + - `Search object { type, queries, query, sources }` - Status discriminator that is always `active`. + Action type "search" - Performs a web search query. - - `"active"` + - `type: "search"` - - `Locked object { reason, type }` + The action type. - Indicates that a thread is locked and cannot accept new input. + - `"search"` - - `reason: string` + - `queries: optional array of string` - Reason that the thread was locked. Defaults to null when no reason is recorded. + The search queries. - - `type: "locked"` + - `query: optional string` - Status discriminator that is always `locked`. + The search query. - - `"locked"` + - `sources: optional array of object { type, url }` - - `Closed object { reason, type }` + The sources used in the search. - Indicates that a thread has been closed. + - `type: "url"` - - `reason: string` + The type of source. Always `url`. - Reason that the thread was closed. Defaults to null when no reason is recorded. + - `"url"` - - `type: "closed"` + - `url: string` - Status discriminator that is always `closed`. + The URL of the source. - - `"closed"` + - `OpenPage object { type, url }` - - `title: string` + Action type "open_page" - Opens a specific URL from search results. - Optional human-readable title for the thread. Defaults to null when no title has been generated. + - `type: "open_page"` - - `user: string` + The action type. - Free-form string that identifies your end user who owns the thread. + - `"open_page"` -### Example + - `url: optional string` -```http -curl https://api.openai.com/v1/chatkit/threads/$THREAD_ID \ - -H 'OpenAI-Beta: chatkit_beta=v1' \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + The URL opened by the model. -#### Response + - `FindInPage object { pattern, type, url }` -```json -{ - "id": "cthr_def456", - "created_at": 1712345600, - "object": "chatkit.thread", - "status": { - "type": "active" - }, - "title": "Demo feedback", - "user": "user_456" -} -``` + Action type "find_in_page": Searches for a pattern within a loaded page. -### Example + - `pattern: string` -```http -curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - -H "OpenAI-Beta: chatkit_beta=v1" \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + The pattern or text to search for within the page. -#### Response + - `type: "find_in_page"` -```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 action type. -## Delete ChatKit thread + - `"find_in_page"` -**delete** `/chatkit/threads/{thread_id}` + - `url: string` -Delete ChatKit thread + The URL of the page searched for the pattern. -### Path Parameters + - `status: "in_progress" or "searching" or "completed" or "failed"` -- `thread_id: string` + The status of the web search tool call. -### Returns + - `"in_progress"` -- `id: string` + - `"searching"` - Identifier of the deleted thread. + - `"completed"` -- `deleted: boolean` + - `"failed"` - Indicates that the thread has been deleted. + - `type: "web_search_call"` -- `object: "chatkit.thread.deleted"` + The type of the web search tool call. Always `web_search_call`. - Type discriminator that is always `chatkit.thread.deleted`. + - `"web_search_call"` - - `"chatkit.thread.deleted"` + - `agent: optional object { agent_name }` -### Example + The agent that produced this item. -```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" -``` + - `agent_name: string` -#### Response + The canonical name of the agent that produced this item. -```json -{ - "id": "id", - "deleted": true, - "object": "chatkit.thread.deleted" -} -``` + - `FunctionCall object { arguments, call_id, name, 6 more }` -## List ChatKit threads + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. -**get** `/chatkit/threads` + - `arguments: string` -List ChatKit threads + A JSON string of the arguments to pass to the function. -### Query Parameters + - `call_id: string` -- `after: optional string` + The unique ID of the function tool call generated by the model. - List items created after this thread item ID. Defaults to null for the first page. + - `name: string` -- `before: optional string` + The name of the function to run. - List items created before this thread item ID. Defaults to null for the newest results. + - `type: "function_call"` -- `limit: optional number` + The type of the function tool call. Always `function_call`. - Maximum number of thread items to return. Defaults to 20. + - `"function_call"` -- `order: optional "asc" or "desc"` + - `id: optional string` - Sort order for results by creation time. Defaults to `desc`. + The unique ID of the function tool call. - - `"asc"` + - `agent: optional object { agent_name }` - - `"desc"` + The agent that produced this item. -- `user: optional string` + - `agent_name: string` - Filter threads that belong to this user identifier. Defaults to null to return all users. + The canonical name of the agent that produced this item. -### Returns + - `caller: optional object { type } or object { caller_id, type }` -- `data: array of ChatKitThread` + The execution context that produced this tool call. - A list of items + - `Direct object { type }` - - `id: string` + - `type: "direct"` - Identifier of the thread. + - `"direct"` - - `created_at: number` + - `Program object { caller_id, type }` - Unix timestamp (in seconds) for when the thread was created. + - `caller_id: string` - - `object: "chatkit.thread"` + The call ID of the program item that produced this tool call. - Type discriminator that is always `chatkit.thread`. + - `type: "program"` - - `"chatkit.thread"` + - `"program"` - - `status: object { type } or object { reason, type } or object { reason, type }` + - `namespace: optional string` - Current status for the thread. Defaults to `active` for newly created threads. + The namespace of the function to run. - - `Active object { type }` + - `status: optional "in_progress" or "completed" or "incomplete"` - Indicates that a thread is active. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `type: "active"` + - `"in_progress"` - Status discriminator that is always `active`. + - `"completed"` - - `"active"` + - `"incomplete"` - - `Locked object { reason, type }` + - `FunctionCallOutput object { call_id, output, type, 4 more }` - Indicates that a thread is locked and cannot accept new input. + The output of a function tool call. - - `reason: string` + - `call_id: string` - Reason that the thread was locked. Defaults to null when no reason is recorded. + The unique ID of the function tool call generated by the model. - - `type: "locked"` + - `output: string or array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` - Status discriminator that is always `locked`. + Text, image, or file output of the function tool call. - - `"locked"` + - `string` - - `Closed object { reason, type }` + A JSON string of the output of the function tool call. - Indicates that a thread has been closed. + - `array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` - - `reason: string` + An array of content outputs (text, image, file) for the function tool call. - Reason that the thread was closed. Defaults to null when no reason is recorded. + - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` - - `type: "closed"` + A text input to the model. - Status discriminator that is always `closed`. + - `text: string` - - `"closed"` + The text input to the model. - - `title: string` + - `type: "input_text"` - Optional human-readable title for the thread. Defaults to null when no title has been generated. + The type of the input item. Always `input_text`. - - `user: string` + - `"input_text"` - Free-form string that identifies your end user who owns the thread. + - `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. - The ID of the first item in the list. + - `mode: "explicit"` -- `has_more: boolean` + The breakpoint mode. Always `explicit`. - Whether there are more items available. + - `"explicit"` -- `last_id: string` + - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` - The ID of the last item in the list. + An image input to the model. Learn about [image inputs](/docs/guides/vision) -- `object: "list"` + - `type: "input_image"` - The type of object returned, must be `list`. + The type of the input item. Always `input_image`. - - `"list"` + - `"input_image"` -### Example + - `detail: optional "low" or "high" or "auto" or "original"` -```http -curl https://api.openai.com/v1/chatkit/threads \ - -H 'OpenAI-Beta: chatkit_beta=v1' \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + 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 -{ - "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" -} -``` + - `"high"` -### Example + - `"auto"` -```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" -``` + - `"original"` -#### Response + - `file_id: optional string` -```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 ID of the file to be sent to the model. -## Domain Types + - `image_url: optional string` -### Chat Session + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. -- `ChatSession object { id, chatkit_configuration, client_secret, 7 more }` + - `prompt_cache_breakpoint: optional object { mode }` - Represents a ChatKit session and its resolved configuration. + Marks the exact end of a reusable 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"` - Identifier for the ChatKit session. + The breakpoint mode. Always `explicit`. - - `chatkit_configuration: ChatSessionChatKitConfiguration` + - `"explicit"` - Resolved ChatKit feature configuration for the session. + - `BetaResponseInputFileContent object { type, detail, file_data, 4 more }` - - `automatic_thread_titling: ChatSessionAutomaticThreadTitling` + A file input to the model. - Automatic thread titling preferences. + - `type: "input_file"` - - `enabled: boolean` + The type of the input item. Always `input_file`. - Whether automatic thread titling is enabled. + - `"input_file"` - - `file_upload: ChatSessionFileUpload` + - `detail: optional "auto" or "low" or "high"` - Upload settings for the session. + 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`. - - `enabled: boolean` + - `"auto"` - Indicates if uploads are enabled for the session. + - `"low"` - - `max_file_size: number` + - `"high"` - Maximum upload size in megabytes. + - `file_data: optional string` - - `max_files: number` + The base64-encoded data of the file to be sent to the model. - Maximum number of uploads allowed during the session. + - `file_id: optional string` - - `history: ChatSessionHistory` + The ID of the file to be sent to the model. - History retention configuration. + - `file_url: optional string` - - `enabled: boolean` + The URL of the file to be sent to the model. - Indicates if chat history is persisted for the session. + - `filename: optional string` - - `recent_threads: number` + The name of the file to be sent to the model. - Number of prior threads surfaced in history views. Defaults to null when all history is retained. + - `prompt_cache_breakpoint: optional object { mode }` - - `client_secret: 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. - Ephemeral client secret that authenticates session requests. + - `mode: "explicit"` - - `expires_at: number` + The breakpoint mode. Always `explicit`. - Unix timestamp (in seconds) for when the session expires. + - `"explicit"` - - `max_requests_per_1_minute: number` + - `type: "function_call_output"` - Convenience copy of the per-minute request limit. + The type of the function tool call output. Always `function_call_output`. - - `object: "chatkit.session"` + - `"function_call_output"` - Type discriminator that is always `chatkit.session`. + - `id: optional string` - - `"chatkit.session"` + The unique ID of the function tool call output. Populated when this item is returned via API. - - `rate_limits: ChatSessionRateLimits` + - `agent: optional object { agent_name }` - Resolved rate limit values. + The agent that produced this item. - - `max_requests_per_1_minute: number` + - `agent_name: string` - Maximum allowed requests per one-minute window. + The canonical name of the agent that produced this item. - - `status: ChatSessionStatus` + - `caller: optional object { type } or object { caller_id, type }` - Current lifecycle state of the session. + The execution context that produced this tool call. - - `"active"` + - `Direct object { type }` - - `"expired"` + - `type: "direct"` - - `"cancelled"` + The caller type. Always `direct`. - - `user: string` + - `"direct"` - User identifier associated with the session. + - `Program object { caller_id, type }` - - `workflow: ChatKitWorkflow` + - `caller_id: string` - Workflow metadata for the session. + The call ID of the program item that produced this tool call. - - `id: string` + - `type: "program"` - Identifier of the workflow backing the session. + The caller type. 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. + - `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. - - `boolean` + - `"in_progress"` - - `number` + - `"completed"` - - `tracing: object { enabled }` + - `"incomplete"` - Tracing settings applied to the workflow. + - `AgentMessage object { author, content, recipient, 3 more }` - - `enabled: boolean` + A message routed between agents. - Indicates whether tracing is enabled. + - `author: string` - - `version: string` + The sending agent identity. - Specific workflow version used for the session. Defaults to null when using the latest deployment. + - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` -### Chat Session Automatic Thread Titling + Plaintext, image, or encrypted content sent between agents. -- `ChatSessionAutomaticThreadTitling object { enabled }` + - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` - Automatic thread title preferences for the session. + A text input to the model. - - `enabled: boolean` + - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` - Whether automatic thread titling is enabled. + An image input to the model. Learn about [image inputs](/docs/guides/vision) -### Chat Session ChatKit Configuration + - `EncryptedContent object { encrypted_content, type }` -- `ChatSessionChatKitConfiguration object { automatic_thread_titling, file_upload, history }` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - ChatKit configuration for the session. + - `encrypted_content: string` - - `automatic_thread_titling: ChatSessionAutomaticThreadTitling` + Opaque encrypted content. - Automatic thread titling preferences. + - `type: "encrypted_content"` - - `enabled: boolean` + The type of the input item. Always `encrypted_content`. - Whether automatic thread titling is enabled. + - `"encrypted_content"` - - `file_upload: ChatSessionFileUpload` + - `recipient: string` - Upload settings for the session. + The destination agent identity. - - `enabled: boolean` + - `type: "agent_message"` - Indicates if uploads are enabled for the session. + The item type. Always `agent_message`. - - `max_file_size: number` + - `"agent_message"` - Maximum upload size in megabytes. + - `id: optional string` - - `max_files: number` + The unique ID of this agent message item. - Maximum number of uploads allowed during the session. + - `agent: optional object { agent_name }` - - `history: ChatSessionHistory` + The agent that produced this item. - History retention configuration. + - `agent_name: string` - - `enabled: boolean` + The canonical name of the agent that produced this item. - Indicates if chat history is persisted for the session. + - `MultiAgentCall object { action, arguments, call_id, 3 more }` - - `recent_threads: number` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - Number of prior threads surfaced in history views. Defaults to null when all history is retained. + The multi-agent action that was executed. -### Chat Session ChatKit Configuration Param + - `"spawn_agent"` -- `ChatSessionChatKitConfigurationParam object { automatic_thread_titling, file_upload, history }` + - `"interrupt_agent"` - Optional per-session configuration settings for ChatKit behavior. + - `"list_agents"` - - `automatic_thread_titling: optional object { enabled }` + - `"send_message"` - Configuration for automatic thread titling. When omitted, automatic thread titling is enabled by default. + - `"followup_task"` - - `enabled: optional boolean` + - `"wait_agent"` - Enable automatic thread title generation. Defaults to true. + - `arguments: string` - - `file_upload: optional object { enabled, max_file_size, max_files }` + The action arguments as a JSON string. - Configuration for upload enablement and limits. When omitted, uploads are disabled by default (max_files 10, max_file_size 512 MB). + - `call_id: string` - - `enabled: optional boolean` + The unique ID linking this call to its output. - Enable uploads for this session. Defaults to false. + - `type: "multi_agent_call"` - - `max_file_size: optional number` + The item type. Always `multi_agent_call`. - Maximum size in megabytes for each uploaded file. Defaults to 512 MB, which is the maximum allowable size. + - `"multi_agent_call"` - - `max_files: optional number` + - `id: optional string` - Maximum number of files that can be uploaded to the session. Defaults to 10. + The unique ID of this multi-agent call. - - `history: optional object { enabled, recent_threads }` + - `agent: optional object { agent_name }` - Configuration for chat history retention. When omitted, history is enabled by default with no limit on recent_threads (null). + The agent that produced this item. - - `enabled: optional boolean` + - `agent_name: string` - Enables chat users to access previous ChatKit threads. Defaults to true. + The canonical name of the agent that produced this item. - - `recent_threads: optional number` + - `MultiAgentCallOutput object { action, call_id, output, 3 more }` - Number of recent ChatKit threads users have access to. Defaults to unlimited when unset. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` -### Chat Session Expires After Param + The multi-agent action that produced this result. -- `ChatSessionExpiresAfterParam object { anchor, seconds }` + - `"spawn_agent"` - Controls when the session expires relative to an anchor timestamp. + - `"interrupt_agent"` - - `anchor: "created_at"` + - `"list_agents"` - Base timestamp used to calculate expiration. Currently fixed to `created_at`. + - `"send_message"` - - `"created_at"` + - `"followup_task"` - - `seconds: number` + - `"wait_agent"` - Number of seconds after the anchor when the session expires. + - `call_id: string` -### Chat Session File Upload + The unique ID of the multi-agent call. -- `ChatSessionFileUpload object { enabled, max_file_size, max_files }` + - `output: array of object { text, type, annotations }` - Upload permissions and limits applied to the session. + Text output returned by the multi-agent action. - - `enabled: boolean` + - `text: string` - Indicates if uploads are enabled for the session. + The text content. - - `max_file_size: number` + - `type: "output_text"` - Maximum upload size in megabytes. + The content type. Always `output_text`. - - `max_files: number` + - `"output_text"` - Maximum number of uploads allowed during the session. + - `annotations: optional array of object { file_id, filename, index, type } or array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` -### Chat Session History + Citations associated with the text content. -- `ChatSessionHistory object { enabled, recent_threads }` + - `array of object { file_id, filename, index, type }` - History retention preferences returned for the session. + - `file_id: string` - - `enabled: boolean` + The ID of the file. - Indicates if chat history is persisted for the session. + - `filename: string` - - `recent_threads: number` + The filename of the file cited. - Number of prior threads surfaced in history views. Defaults to null when all history is retained. + - `index: number` -### Chat Session Rate Limits + The index of the file in the list of files. -- `ChatSessionRateLimits object { max_requests_per_1_minute }` + - `type: "file_citation"` - Active per-minute request limit for the session. + The citation type. Always `file_citation`. - - `max_requests_per_1_minute: number` + - `"file_citation"` - Maximum allowed requests per one-minute window. + - `array of object { end_index, start_index, title, 2 more }` -### Chat Session Rate Limits Param + - `end_index: number` -- `ChatSessionRateLimitsParam object { max_requests_per_1_minute }` + The index of the last character of the citation in the message. - Controls request rate limits for the session. + - `start_index: number` - - `max_requests_per_1_minute: optional number` + The index of the first character of the citation in the message. - Maximum number of requests allowed per minute for the session. Defaults to 10. + - `title: string` -### Chat Session Status + The title of the cited resource. -- `ChatSessionStatus = "active" or "expired" or "cancelled"` + - `type: "url_citation"` - - `"active"` + The citation type. Always `url_citation`. - - `"expired"` + - `"url_citation"` - - `"cancelled"` + - `url: string` -### Chat Session Workflow Param + The URL of the cited resource. -- `ChatSessionWorkflowParam object { id, state_variables, tracing, version }` + - `array of object { container_id, end_index, file_id, 3 more }` - Workflow reference and overrides applied to the chat session. + - `container_id: string` - - `id: string` + The ID of the container. - Identifier for the workflow invoked by the session. + - `end_index: number` - - `state_variables: optional map[string or boolean or number]` + The index of the last character of the citation in the message. - 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. + - `file_id: string` - - `string` + The ID of the container file. - - `boolean` + - `filename: string` - - `number` + The filename of the container file cited. - - `tracing: optional object { enabled }` + - `start_index: number` - Optional tracing overrides for the workflow invocation. When omitted, tracing is enabled by default. + The index of the first character of the citation in the message. - - `enabled: optional boolean` + - `type: "container_file_citation"` - Whether tracing is enabled during the session. Defaults to true. + The citation type. Always `container_file_citation`. - - `version: optional string` + - `"container_file_citation"` - Specific workflow version to run. Defaults to the latest deployed version. + - `type: "multi_agent_call_output"` -### ChatKit Attachment + The item type. Always `multi_agent_call_output`. -- `ChatKitAttachment object { id, mime_type, name, 2 more }` + - `"multi_agent_call_output"` - Attachment metadata included on thread items. + - `id: optional string` - - `id: string` + The unique ID of this multi-agent call output. - 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. + - `ToolSearchCall object { arguments, type, id, 4 more }` - - `preview_url: string` + - `arguments: unknown` - Preview URL for rendering the attachment inline. + The arguments supplied to the tool search call. - - `type: "image" or "file"` + - `type: "tool_search_call"` - Attachment discriminator. + The item type. Always `tool_search_call`. - - `"image"` + - `"tool_search_call"` - - `"file"` + - `id: optional string` -### ChatKit Response Output Text + The unique ID of this tool search call. -- `ChatKitResponseOutputText object { annotations, text, type }` + - `agent: optional object { agent_name }` - Assistant response text accompanied by optional annotations. + The agent that produced this item. - - `annotations: array of object { source, type } or object { source, type }` + - `agent_name: string` - Ordered list of annotations attached to the response text. + The canonical name of the agent that produced this item. - - `File object { source, type }` + - `call_id: optional string` - Annotation that references an uploaded file. + The unique ID of the tool search call generated by the model. - - `source: object { filename, type }` + - `execution: optional "server" or "client"` - File attachment referenced by the annotation. + Whether tool search was executed by the server or by the client. - - `filename: string` + - `"server"` - Filename referenced by the annotation. + - `"client"` - - `type: "file"` + - `status: optional "in_progress" or "completed" or "incomplete"` - Type discriminator that is always `file`. + The status of the tool search call. - - `"file"` + - `"in_progress"` - - `type: "file"` + - `"completed"` - Type discriminator that is always `file` for this annotation. + - `"incomplete"` - - `"file"` + - `ToolSearchOutput object { tools, type, id, 4 more }` - - `URL object { source, type }` + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - Annotation that references a URL. + The loaded tool definitions returned by the tool search output. - - `source: object { type, url }` + - `Function object { name, parameters, strict, 5 more }` - URL referenced by the annotation. + 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: "url"` + - `name: string` - Type discriminator that is always `url`. + The name of the function to call. - - `"url"` + - `parameters: map[unknown]` - - `url: string` + A JSON schema object describing the parameters of the function. - URL referenced by the annotation. + - `strict: boolean` - - `type: "url"` + Whether strict parameter validation is enforced for this function tool. - Type discriminator that is always `url` for this annotation. + - `type: "function"` - - `"url"` + The type of the function tool. Always `function`. - - `text: string` + - `"function"` - Assistant generated text. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `type: "output_text"` + The tool invocation context(s). - Type discriminator that is always `output_text`. + - `"direct"` - - `"output_text"` + - `"programmatic"` -### ChatKit Thread + - `defer_loading: optional boolean` -- `ChatKitThread object { id, created_at, object, 3 more }` + Whether this function is deferred and loaded via tool search. - Represents a ChatKit thread and its current status. + - `description: optional string` - - `id: string` + A description of the function. Used by the model to determine whether or not to call the function. - Identifier of the thread. + - `output_schema: optional map[unknown]` - - `created_at: number` + A JSON schema object describing the JSON value encoded in string outputs for this function. - Unix timestamp (in seconds) for when the thread was created. + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - - `object: "chatkit.thread"` + 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 discriminator that is always `chatkit.thread`. + - `type: "file_search"` - - `"chatkit.thread"` + The type of the file search tool. Always `file_search`. - - `status: object { type } or object { reason, type } or object { reason, type }` + - `"file_search"` - Current status for the thread. Defaults to `active` for newly created threads. + - `vector_store_ids: array of string` - - `Active object { type }` + The IDs of the vector stores to search. - Indicates that a thread is active. + - `filters: optional object { key, type, value } or object { filters, type }` - - `type: "active"` + A filter to apply. - Status discriminator that is always `active`. + - `ComparisonFilter object { key, type, value }` - - `"active"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `Locked object { reason, type }` + - `key: string` - Indicates that a thread is locked and cannot accept new input. + The key to compare against the value. - - `reason: string` + - `type: "eq" or "ne" or "gt" or 5 more` - Reason that the thread was locked. Defaults to null when no reason is recorded. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `type: "locked"` + - `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 - Status discriminator that is always `locked`. + - `"eq"` - - `"locked"` + - `"ne"` - - `Closed object { reason, type }` + - `"gt"` - Indicates that a thread has been closed. + - `"gte"` - - `reason: string` + - `"lt"` - Reason that the thread was closed. Defaults to null when no reason is recorded. + - `"lte"` - - `type: "closed"` + - `"in"` - Status discriminator that is always `closed`. + - `"nin"` - - `"closed"` + - `value: string or number or boolean or array of string or number` - - `title: string` + The value to compare against the attribute key; supports string, number, or boolean types. - Optional human-readable title for the thread. Defaults to null when no title has been generated. + - `string` - - `user: string` + - `number` - Free-form string that identifies your end user who owns the thread. + - `boolean` -### ChatKit Thread Assistant Message Item + - `array of string or number` -- `ChatKitThreadAssistantMessageItem object { id, content, created_at, 3 more }` + - `string` - Assistant-authored message within a thread. + - `number` - - `id: string` + - `CompoundFilter object { filters, type }` - Identifier of the thread item. + Combine multiple filters using `and` or `or`. - - `content: array of ChatKitResponseOutputText` + - `filters: array of object { key, type, value } or unknown` - Ordered assistant response segments. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `annotations: array of object { source, type } or object { source, type }` + - `ComparisonFilter object { key, type, value }` - Ordered list of annotations attached to the response text. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `File object { source, type }` + - `key: string` - Annotation that references an uploaded file. + The key to compare against the value. - - `source: object { filename, type }` + - `type: "eq" or "ne" or "gt" or 5 more` - File attachment referenced by the annotation. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `filename: 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 - Filename referenced by the annotation. + - `"eq"` - - `type: "file"` + - `"ne"` - Type discriminator that is always `file`. + - `"gt"` - - `"file"` + - `"gte"` - - `type: "file"` + - `"lt"` - Type discriminator that is always `file` for this annotation. + - `"lte"` - - `"file"` + - `"in"` - - `URL object { source, type }` + - `"nin"` - Annotation that references a URL. + - `value: string or number or boolean or array of string or number` - - `source: object { type, url }` + The value to compare against the attribute key; supports string, number, or boolean types. - URL referenced by the annotation. + - `string` - - `type: "url"` - - Type discriminator that is always `url`. + - `number` - - `"url"` + - `boolean` - - `url: string` + - `array of string or number` - URL referenced by the annotation. + - `string` - - `type: "url"` + - `number` - Type discriminator that is always `url` for this annotation. + - `unknown` - - `"url"` + - `type: "and" or "or"` - - `text: string` + Type of operation: `and` or `or`. - Assistant generated text. + - `"and"` - - `type: "output_text"` + - `"or"` - Type discriminator that is always `output_text`. + - `max_num_results: optional number` - - `"output_text"` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `created_at: number` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - Unix timestamp (in seconds) for when the item was created. + Ranking options for search. - - `object: "chatkit.thread_item"` + - `hybrid_search: optional object { embedding_weight, text_weight }` - Type discriminator that is always `chatkit.thread_item`. + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `"chatkit.thread_item"` + - `embedding_weight: number` - - `thread_id: string` + The weight of the embedding in the reciprocal ranking fusion. - Identifier of the parent thread. + - `text_weight: number` - - `type: "chatkit.assistant_message"` + The weight of the text in the reciprocal ranking fusion. - Type discriminator that is always `chatkit.assistant_message`. + - `ranker: optional "auto" or "default-2024-11-15"` - - `"chatkit.assistant_message"` + The ranker to use for the file search. -### ChatKit Thread Item List + - `"auto"` -- `ChatKitThreadItemList object { data, first_id, has_more, 2 more }` + - `"default-2024-11-15"` - A paginated list of thread items rendered for the ChatKit API. + - `score_threshold: optional number` - - `data: array of ChatKitThreadUserMessageItem or ChatKitThreadAssistantMessageItem or ChatKitWidgetItem or 3 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 list of items + - `Computer object { type }` - - `ChatKitThreadUserMessageItem object { id, attachments, content, 5 more }` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - User-authored messages within a thread. + - `type: "computer"` - - `id: string` + The type of the computer tool. Always `computer`. - Identifier of the thread item. + - `"computer"` - - `attachments: array of ChatKitAttachment` + - `ComputerUsePreview object { display_height, display_width, environment, type }` - Attachments associated with the user message. Defaults to an empty list. + 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` - Identifier for the attachment. + The height of the computer display. - - `mime_type: string` + - `display_width: number` - MIME type of the attachment. + The width of the computer display. - - `name: string` + - `environment: "windows" or "mac" or "linux" or 2 more` - Original display name for the attachment. + The type of computer environment to control. - - `preview_url: string` + - `"windows"` - Preview URL for rendering the attachment inline. + - `"mac"` - - `type: "image" or "file"` + - `"linux"` - Attachment discriminator. + - `"ubuntu"` - - `"image"` + - `"browser"` - - `"file"` + - `type: "computer_use_preview"` - - `content: array of object { text, type } or object { text, type }` + The type of the computer use tool. Always `computer_use_preview`. - Ordered content elements supplied by the user. + - `"computer_use_preview"` - - `InputText object { text, type }` + - `WebSearch object { type, filters, search_context_size, user_location }` - Text block that a user contributed to the thread. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - - `text: string` + - `type: "web_search" or "web_search_2025_08_26"` - Plain-text content supplied by the user. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `type: "input_text"` + - `"web_search"` - Type discriminator that is always `input_text`. + - `"web_search_2025_08_26"` - - `"input_text"` + - `filters: optional object { allowed_domains }` - - `QuotedText object { text, type }` + Filters for the search. - Quoted snippet that the user referenced in their message. + - `allowed_domains: optional array of string` - - `text: string` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - Quoted text content. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `type: "quoted_text"` + - `search_context_size: optional "low" or "medium" or "high"` - Type discriminator that is always `quoted_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. - - `"quoted_text"` + - `"low"` - - `created_at: number` + - `"medium"` - Unix timestamp (in seconds) for when the item was created. + - `"high"` - - `inference_options: object { model, tool_choice }` + - `user_location: optional object { city, country, region, 2 more }` - Inference overrides applied to the message. Defaults to null when unset. + The approximate location of the user. - - `model: string` + - `city: optional string` - Model name that generated the response. Defaults to null when using the session default. + Free text input for the city of the user, e.g. `San Francisco`. - - `tool_choice: object { id }` + - `country: optional string` - Preferred tool to invoke. Defaults to null when ChatKit should auto-select. + 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` - Identifier of the requested tool. + Free text input for the region of the user, e.g. `California`. - - `object: "chatkit.thread_item"` + - `timezone: optional string` - Type discriminator that is always `chatkit.thread_item`. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `"chatkit.thread_item"` + - `type: optional "approximate"` - - `thread_id: string` + The type of location approximation. Always `approximate`. - Identifier of the parent thread. + - `"approximate"` - - `type: "chatkit.user_message"` + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `"chatkit.user_message"` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - - `ChatKitThreadAssistantMessageItem object { id, content, created_at, 3 more }` + - `server_label: string` - Assistant-authored message within a thread. + A label for this MCP server, used to identify it in tool calls. - - `id: string` + - `type: "mcp"` - Identifier of the thread item. + The type of the MCP tool. Always `mcp`. - - `content: array of ChatKitResponseOutputText` + - `"mcp"` - Ordered assistant response segments. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `annotations: array of object { source, type } or object { source, type }` + The tool invocation context(s). - Ordered list of annotations attached to the response text. + - `"direct"` - - `File object { source, type }` + - `"programmatic"` - Annotation that references an uploaded file. + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `source: object { filename, type }` + List of allowed tool names or a filter object. - File attachment referenced by the annotation. + - `McpAllowedTools = array of string` - - `filename: string` + A string array of allowed tool names - Filename referenced by the annotation. + - `McpToolFilter object { read_only, tool_names }` - - `type: "file"` + A filter object to specify which tools are allowed. - Type discriminator that is always `file`. + - `read_only: optional boolean` - - `"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. - - `type: "file"` + - `tool_names: optional array of string` - Type discriminator that is always `file` for this annotation. + List of allowed tool names. - - `"file"` + - `authorization: optional string` - - `URL object { source, 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. - Annotation that references a URL. + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `source: object { 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). - URL referenced by the annotation. + Currently supported `connector_id` values are: - - `type: "url"` + - 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 discriminator that is always `url`. + - `"connector_dropbox"` - - `"url"` + - `"connector_gmail"` - - `url: string` + - `"connector_googlecalendar"` - URL referenced by the annotation. + - `"connector_googledrive"` - - `type: "url"` + - `"connector_microsoftteams"` - Type discriminator that is always `url` for this annotation. + - `"connector_outlookcalendar"` - - `"url"` + - `"connector_outlookemail"` - - `text: string` + - `"connector_sharepoint"` - Assistant generated text. + - `defer_loading: optional boolean` - - `type: "output_text"` + Whether this MCP tool is deferred and discovered via tool search. - Type discriminator that is always `output_text`. + - `headers: optional map[string]` - - `"output_text"` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `created_at: number` + - `require_approval: optional object { always, never } or "always" or "never"` - Unix timestamp (in seconds) for when the item was created. + Specify which of the MCP server's tools require approval. - - `object: "chatkit.thread_item"` + - `McpToolApprovalFilter object { always, never }` - Type discriminator that is always `chatkit.thread_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. - - `"chatkit.thread_item"` + - `always: optional object { read_only, tool_names }` - - `thread_id: string` + A filter object to specify which tools are allowed. - Identifier of the parent thread. + - `read_only: optional boolean` - - `type: "chatkit.assistant_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. - Type discriminator that is always `chatkit.assistant_message`. + - `tool_names: optional array of string` - - `"chatkit.assistant_message"` + List of allowed tool names. - - `ChatKitWidgetItem object { id, created_at, object, 3 more }` + - `never: optional object { read_only, tool_names }` - Thread item that renders a widget payload. + A filter object to specify which tools are allowed. - - `id: string` + - `read_only: optional boolean` - Identifier of the thread 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. - - `created_at: number` + - `tool_names: optional array of string` - Unix timestamp (in seconds) for when the item was created. + List of allowed tool names. - - `object: "chatkit.thread_item"` + - `McpToolApprovalSetting = "always" or "never"` - Type discriminator that is always `chatkit.thread_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. - - `"chatkit.thread_item"` + - `"always"` - - `thread_id: string` + - `"never"` - Identifier of the parent thread. + - `server_description: optional string` - - `type: "chatkit.widget"` + Optional description of the MCP server, used to provide more context. - Type discriminator that is always `chatkit.widget`. + - `server_url: optional string` - - `"chatkit.widget"` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `widget: string` + - `tunnel_id: optional string` - Serialized widget payload rendered in the UI. + 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. - - `ChatKitClientToolCall object { id, arguments, call_id, 7 more }` + - `CodeInterpreter object { container, type, allowed_callers }` - Record of a client side tool invocation initiated by the assistant. + A tool that runs Python code to help generate a response to a prompt. - - `id: string` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - Identifier of the thread 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. - - `arguments: string` + - `string` - JSON-encoded arguments that were sent to the tool. + The container ID. - - `call_id: string` + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - Identifier for the client tool call. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `created_at: number` + - `type: "auto"` - Unix timestamp (in seconds) for when the item was created. + Always `auto`. - - `name: string` + - `"auto"` - Tool name that was invoked. + - `file_ids: optional array of string` - - `object: "chatkit.thread_item"` + An optional list of uploaded files to make available to your code. - Type discriminator that is always `chatkit.thread_item`. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `"chatkit.thread_item"` + The memory limit for the code interpreter container. - - `output: string` + - `"1g"` - JSON-encoded output captured from the tool. Defaults to null while execution is in progress. + - `"4g"` - - `status: "in_progress" or "completed"` + - `"16g"` - Execution status for the tool call. + - `"64g"` - - `"in_progress"` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `"completed"` + Network access policy for the container. - - `thread_id: string` + - `BetaContainerNetworkPolicyDisabled object { type }` - Identifier of the parent thread. + - `type: "disabled"` - - `type: "chatkit.client_tool_call"` + Disable outbound network access. Always `disabled`. - Type discriminator that is always `chatkit.client_tool_call`. + - `"disabled"` - - `"chatkit.client_tool_call"` + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `ChatKitTask object { id, created_at, heading, 5 more }` + - `allowed_domains: array of string` - Task emitted by the workflow to show progress and status updates. + A list of allowed domains when type is `allowlist`. - - `id: string` + - `type: "allowlist"` - Identifier of the thread item. + Allow outbound network access only to specified domains. Always `allowlist`. - - `created_at: number` + - `"allowlist"` - Unix timestamp (in seconds) for when the item was created. + - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` - - `heading: string` + Optional domain-scoped secrets for allowlisted domains. - Optional heading for the task. Defaults to null when not provided. + - `domain: string` - - `object: "chatkit.thread_item"` + The domain associated with the secret. - Type discriminator that is always `chatkit.thread_item`. + - `name: string` - - `"chatkit.thread_item"` + The name of the secret to inject for the domain. - - `summary: string` + - `value: string` - Optional summary that describes the task. Defaults to null when omitted. + The secret value to inject for the domain. - - `task_type: "custom" or "thought"` + - `type: "code_interpreter"` - Subtype for the task. + The type of the code interpreter tool. Always `code_interpreter`. - - `"custom"` + - `"code_interpreter"` - - `"thought"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `thread_id: string` + The tool invocation context(s). - Identifier of the parent thread. + - `"direct"` - - `type: "chatkit.task"` + - `"programmatic"` - Type discriminator that is always `chatkit.task`. + - `ProgrammaticToolCalling object { type }` - - `"chatkit.task"` + - `type: "programmatic_tool_calling"` - - `ChatKitTaskGroup object { id, created_at, object, 3 more }` + The type of the tool. Always `programmatic_tool_calling`. - Collection of workflow tasks grouped together in the thread. + - `"programmatic_tool_calling"` - - `id: string` + - `ImageGeneration object { type, action, background, 9 more }` - Identifier of the thread item. + A tool that generates images using the GPT image models. - - `created_at: number` + - `type: "image_generation"` - Unix timestamp (in seconds) for when the item was created. + The type of the image generation tool. Always `image_generation`. - - `object: "chatkit.thread_item"` + - `"image_generation"` - Type discriminator that is always `chatkit.thread_item`. + - `action: optional "generate" or "edit" or "auto"` - - `"chatkit.thread_item"` + Whether to generate a new image or edit an existing image. Default: `auto`. - - `tasks: array of object { heading, summary, type }` + - `"generate"` - Tasks included in the group. + - `"edit"` - - `heading: string` + - `"auto"` - Optional heading for the grouped task. Defaults to null when not provided. + - `background: optional "transparent" or "opaque" or "auto"` - - `summary: string` + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - Optional summary that describes the grouped task. Defaults to null when omitted. + - `"transparent"` - - `type: "custom" or "thought"` + - `"opaque"` - Subtype for the grouped task. + - `"auto"` - - `"custom"` + - `input_fidelity: optional "high" or "low"` - - `"thought"` + 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`. - - `thread_id: string` + - `"high"` - Identifier of the parent thread. + - `"low"` - - `type: "chatkit.task_group"` + - `input_image_mask: optional object { file_id, image_url }` - Type discriminator that is always `chatkit.task_group`. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `"chatkit.task_group"` + - `file_id: optional string` - - `first_id: string` + File ID for the mask image. - The ID of the first item in the list. + - `image_url: optional string` - - `has_more: boolean` + Base64-encoded mask image. - Whether there are more items available. + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `last_id: string` + The image generation model to use. Default: `gpt-image-1`. - The ID of the last item in the list. + - `string` - - `object: "list"` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - The type of object returned, must be `list`. + The image generation model to use. Default: `gpt-image-1`. - - `"list"` + - `"gpt-image-1"` -### ChatKit Thread User Message Item + - `"gpt-image-1-mini"` -- `ChatKitThreadUserMessageItem object { id, attachments, content, 5 more }` + - `"gpt-image-1.5"` - User-authored messages within a thread. + - `moderation: optional "auto" or "low"` - - `id: string` + Moderation level for the generated image. Default: `auto`. - Identifier of the thread item. + - `"auto"` - - `attachments: array of ChatKitAttachment` + - `"low"` - Attachments associated with the user message. Defaults to an empty list. + - `output_compression: optional number` - - `id: string` + Compression level for the output image. Default: 100. - Identifier for the attachment. + - `output_format: optional "png" or "webp" or "jpeg"` - - `mime_type: string` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - MIME type of the attachment. + - `"png"` - - `name: string` + - `"webp"` - Original display name for the attachment. + - `"jpeg"` - - `preview_url: string` + - `partial_images: optional number` - Preview URL for rendering the attachment inline. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `type: "image" or "file"` + - `quality: optional "low" or "medium" or "high" or "auto"` - Attachment discriminator. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `"image"` + - `"low"` - - `"file"` + - `"medium"` - - `content: array of object { text, type } or object { text, type }` + - `"high"` - Ordered content elements supplied by the user. + - `"auto"` - - `InputText object { text, type }` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - Text block that a user contributed to the thread. + 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` + - `string` - Plain-text content supplied by the user. + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `type: "input_text"` + 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 discriminator that is always `input_text`. + - `"1024x1024"` - - `"input_text"` + - `"1024x1536"` - - `QuotedText object { text, type }` + - `"1536x1024"` - Quoted snippet that the user referenced in their message. + - `"auto"` - - `text: string` + - `LocalShell object { type }` - Quoted text content. + A tool that allows the model to execute shell commands in a local environment. - - `type: "quoted_text"` + - `type: "local_shell"` - Type discriminator that is always `quoted_text`. + The type of the local shell tool. Always `local_shell`. - - `"quoted_text"` + - `"local_shell"` - - `created_at: number` + - `Shell object { type, allowed_callers, environment }` - Unix timestamp (in seconds) for when the item was created. + A tool that allows the model to execute shell commands. - - `inference_options: object { model, tool_choice }` + - `type: "shell"` - Inference overrides applied to the message. Defaults to null when unset. + The type of the shell tool. Always `shell`. - - `model: string` + - `"shell"` - Model name that generated the response. Defaults to null when using the session default. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `tool_choice: object { id }` + The tool invocation context(s). - Preferred tool to invoke. Defaults to null when ChatKit should auto-select. + - `"direct"` - - `id: string` + - `"programmatic"` - Identifier of the requested tool. + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - `object: "chatkit.thread_item"` + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - Type discriminator that is always `chatkit.thread_item`. + - `type: "container_auto"` - - `"chatkit.thread_item"` + Automatically creates a container for this request - - `thread_id: string` + - `"container_auto"` - Identifier of the parent thread. + - `file_ids: optional array of string` - - `type: "chatkit.user_message"` + An optional list of uploaded files to make available to your code. - - `"chatkit.user_message"` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` -### ChatKit Widget Item + The memory limit for the container. -- `ChatKitWidgetItem object { id, created_at, object, 3 more }` + - `"1g"` - Thread item that renders a widget payload. + - `"4g"` - - `id: string` + - `"16g"` - Identifier of the thread item. + - `"64g"` - - `created_at: number` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - Unix timestamp (in seconds) for when the item was created. + Network access policy for the container. - - `object: "chatkit.thread_item"` + - `BetaContainerNetworkPolicyDisabled object { type }` - Type discriminator that is always `chatkit.thread_item`. + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `"chatkit.thread_item"` + - `skills: optional array of BetaSkillReference or BetaInlineSkill` - - `thread_id: string` + An optional list of skills referenced by id or inline data. - Identifier of the parent thread. + - `BetaSkillReference object { skill_id, type, version }` - - `type: "chatkit.widget"` + - `skill_id: string` - Type discriminator that is always `chatkit.widget`. + The ID of the referenced skill. - - `"chatkit.widget"` + - `type: "skill_reference"` - - `widget: string` + References a skill created with the /v1/skills endpoint. - Serialized widget payload rendered in the UI. + - `"skill_reference"` -### Thread Delete Response + - `version: optional string` -- `ThreadDeleteResponse object { id, deleted, object }` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - Confirmation payload returned after deleting a thread. + - `BetaInlineSkill object { description, name, source, type }` - - `id: string` + - `description: string` - Identifier of the deleted thread. + The description of the skill. - - `deleted: boolean` + - `name: string` - Indicates that the thread has been deleted. + The name of the skill. - - `object: "chatkit.thread.deleted"` + - `source: BetaInlineSkillSource` - Type discriminator that is always `chatkit.thread.deleted`. + Inline skill payload - - `"chatkit.thread.deleted"` + - `data: string` -# Assistants + Base64-encoded skill zip bundle. -## List assistants + - `media_type: "application/zip"` -**get** `/assistants` + The media type of the inline skill payload. Must be `application/zip`. -List assistants + - `"application/zip"` -### Query Parameters + - `type: "base64"` -- `after: optional string` + The type of the inline skill source. Must be `base64`. - 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. + - `"base64"` -- `before: optional string` + - `type: "inline"` - 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. + Defines an inline skill for this request. -- `limit: optional number` + - `"inline"` - A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. + - `BetaLocalEnvironment object { type, skills }` -- `order: optional "asc" or "desc"` + - `type: "local"` - Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. + Use a local computer environment. - - `"asc"` + - `"local"` - - `"desc"` + - `skills: optional array of BetaLocalSkill` -### Returns + An optional list of skills. -- `data: array of Assistant` + - `description: string` - - `id: string` + The description of the skill. - The identifier, which can be referenced in API endpoints. + - `name: string` - - `created_at: number` + The name of the skill. - The Unix timestamp (in seconds) for when the assistant was created. + - `path: string` - - `description: string` + The path to the directory containing the skill. - The description of the assistant. The maximum length is 512 characters. + - `BetaContainerReference object { container_id, type }` - - `instructions: string` + - `container_id: string` - The system instructions that the assistant uses. The maximum length is 256,000 characters. + The ID of the referenced container. - - `metadata: Metadata` + - `type: "container_reference"` - 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. + References a container created with the /v1/containers endpoint - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `"container_reference"` - - `model: string` + - `Custom object { name, type, allowed_callers, 3 more }` - ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](https://platform.openai.com/docs/models) for descriptions of them. + 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 assistant. The maximum length is 256 characters. + The name of the custom tool, used to identify it in tool calls. - - `object: "assistant"` + - `type: "custom"` - The object type, which is always `assistant`. + The type of the custom tool. Always `custom`. - - `"assistant"` + - `"custom"` - - `tools: array of AssistantTool` + - `allowed_callers: optional array of "direct" or "programmatic"` - 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 tool invocation context(s). - - `CodeInterpreterTool object { type }` + - `"direct"` - - `type: "code_interpreter"` + - `"programmatic"` - The type of tool being defined: `code_interpreter` + - `defer_loading: optional boolean` - - `"code_interpreter"` + Whether this tool should be deferred and discovered via tool search. - - `FileSearchTool object { type, file_search }` + - `description: optional string` - - `type: "file_search"` + Optional description of the custom tool, used to provide more context. - The type of tool being defined: `file_search` + - `format: optional object { type } or object { definition, syntax, type }` - - `"file_search"` + The input format for the custom tool. Default is unconstrained text. - - `file_search: optional object { max_num_results, ranking_options }` + - `Text object { type }` - Overrides for the file search tool. + Unconstrained free-form 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. + Unconstrained text format. Always `text`. - Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `"text"` - - `ranking_options: optional object { score_threshold, ranker }` + - `Grammar object { definition, syntax, 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 grammar defined by the user. - See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `definition: string` - - `score_threshold: number` + The grammar definition. - The score threshold for the file search. All values must be a floating point number between 0 and 1. + - `syntax: "lark" or "regex"` - - `ranker: optional "auto" or "default_2024_08_21"` + The syntax of the grammar definition. One of `lark` or `regex`. - The ranker to use for the file search. If not specified will use the `auto` ranker. + - `"lark"` - - `"auto"` + - `"regex"` - - `"default_2024_08_21"` + - `type: "grammar"` - - `FunctionTool object { function, type }` + Grammar format. Always `grammar`. - - `function: FunctionDefinition` + - `"grammar"` - - `name: string` + - `Namespace object { description, name, tools, 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. + Groups function/custom tools under a shared namespace. - - `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. + A description of the namespace shown to the model. - - `parameters: optional FunctionParameters` + - `name: string` - The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + The namespace name used in tool calls (for example, `crm`). - Omitting `parameters` defines a function with an empty parameter list. + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - - `strict: optional boolean` + The function/custom tools available inside this namespace. - 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](https://platform.openai.com/docs/guides/function-calling). + - `Function object { name, type, allowed_callers, 5 more }` - - `type: "function"` + - `name: string` - The type of tool being defined: `function` + - `type: "function"` - `"function"` - - `response_format: optional AssistantResponseFormatOption` + - `allowed_callers: optional array of "direct" or "programmatic"` - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + The tool invocation context(s). - 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](https://platform.openai.com/docs/guides/structured-outputs). + - `"direct"` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `"programmatic"` - **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. + - `defer_loading: optional boolean` - - `"auto"` + Whether this function should be deferred and discovered via tool search. - `auto` is the default value + - `description: optional string` - - `"auto"` + - `output_schema: optional map[unknown]` - - `ResponseFormatText object { type }` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - Default response format. Used to generate text responses. + - `parameters: optional unknown` - - `type: "text"` + - `strict: optional boolean` - The type of response format being defined. Always `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. - - `"text"` + - `Custom object { name, type, allowed_callers, 3 more }` - - `ResponseFormatJSONObject object { type }` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - 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. + - `name: string` - - `type: "json_object"` + The name of the custom tool, used to identify it in tool calls. - The type of response format being defined. Always `json_object`. + - `type: "custom"` - - `"json_object"` + The type of the custom tool. Always `custom`. - - `ResponseFormatJSONSchema object { json_schema, type }` + - `"custom"` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `allowed_callers: optional array of "direct" or "programmatic"` - - `json_schema: object { name, description, schema, strict }` + The tool invocation context(s). - Structured Outputs configuration options, including a JSON Schema. + - `"direct"` - - `name: string` + - `"programmatic"` - 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. + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. - `description: optional string` - A description of what the response format is for, used by the model to - determine how to respond in the format. + Optional description of the custom tool, used to provide more context. - - `schema: optional map[unknown]` + - `format: optional object { type } or 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/). + The input format for the custom tool. Default is unconstrained text. - - `strict: optional boolean` + - `Text object { type }` - 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](https://platform.openai.com/docs/guides/structured-outputs). + Unconstrained free-form text. - - `type: "json_schema"` + - `type: "text"` - The type of response format being defined. Always `json_schema`. + Unconstrained text format. Always `text`. - - `"json_schema"` + - `"text"` - - `temperature: optional number` + - `Grammar object { definition, syntax, type }` - 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 grammar defined by the user. - - `tool_resources: optional object { code_interpreter, file_search }` + - `definition: 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 grammar definition. - - `code_interpreter: optional object { file_ids }` + - `syntax: "lark" or "regex"` - - `file_ids: optional array of string` + The syntax of the grammar definition. One of `lark` or `regex`. - A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter`` tool. There can be a maximum of 20 files associated with the tool. + - `"lark"` - - `file_search: optional object { vector_store_ids }` + - `"regex"` - - `vector_store_ids: optional array of string` + - `type: "grammar"` - The ID of the [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. + Grammar format. Always `grammar`. - - `top_p: optional number` + - `"grammar"` - 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: "namespace"` - We generally recommend altering this or temperature but not both. + The type of the tool. Always `namespace`. -- `first_id: string` + - `"namespace"` -- `has_more: boolean` + - `ToolSearch object { type, description, execution, parameters }` -- `last_id: string` + Hosted or BYOT tool search configuration for deferred tools. -- `object: string` + - `type: "tool_search"` -### Example + The type of the tool. Always `tool_search`. -```http -curl https://api.openai.com/v1/assistants \ - -H 'OpenAI-Beta: assistants=v2' \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + - `"tool_search"` -#### Response + - `description: optional string` -```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" -} -``` + 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/assistants?order=desc&limit=20" \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "OpenAI-Beta: assistants=v2" -``` + Whether tool search is executed by the server or by the client. -#### Response + - `"server"` -```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 -} -``` + - `"client"` -## Create assistant + - `parameters: optional unknown` -**post** `/assistants` + Parameter schema for a client-executed tool search tool. -Create assistant + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` -### Body Parameters + 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: string or ChatModel` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](https://platform.openai.com/docs/models) for descriptions of them. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `string` + - `"web_search_preview"` - - `ChatModel = "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 78 more` + - `"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"` + - `type: "tool_search_output"` - - `"gpt-4.1-nano-2025-04-14"` + The item type. Always `tool_search_output`. - - `"o4-mini"` + - `"tool_search_output"` - - `"o4-mini-2025-04-16"` + - `id: optional string` - - `"o3"` + The unique ID of this tool search output. - - `"o3-2025-04-16"` + - `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"` + - `call_id: optional string` - - `"o1-preview"` + The unique ID of the tool search call generated by the model. - - `"o1-preview-2024-09-12"` + - `execution: optional "server" or "client"` - - `"o1-mini"` + Whether tool search was executed by the server or by the client. - - `"o1-mini-2024-09-12"` + - `"server"` - - `"gpt-4o"` + - `"client"` - - `"gpt-4o-2024-11-20"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"gpt-4o-2024-08-06"` + The status of the tool search output. - - `"gpt-4o-2024-05-13"` + - `"in_progress"` - - `"gpt-4o-audio-preview"` + - `"completed"` - - `"gpt-4o-audio-preview-2024-10-01"` + - `"incomplete"` - - `"gpt-4o-audio-preview-2024-12-17"` + - `AdditionalTools object { role, tools, type, 2 more }` - - `"gpt-4o-audio-preview-2025-06-03"` + - `role: "developer"` - - `"gpt-4o-mini-audio-preview"` + The role that provided the additional tools. Only `developer` is supported. - - `"gpt-4o-mini-audio-preview-2024-12-17"` + - `"developer"` - - `"gpt-4o-search-preview"` + - `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-4o-mini-search-preview"` + A list of additional tools made available at this item. - - `"gpt-4o-search-preview-2025-03-11"` + - `Function object { name, parameters, strict, 5 more }` - - `"gpt-4o-mini-search-preview-2025-03-11"` + 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). - - `"chatgpt-4o-latest"` + - `name: string` - - `"codex-mini-latest"` + The name of the function to call. - - `"gpt-4o-mini"` + - `parameters: map[unknown]` - - `"gpt-4o-mini-2024-07-18"` + A JSON schema object describing the parameters of the function. - - `"gpt-4-turbo"` + - `strict: boolean` - - `"gpt-4-turbo-2024-04-09"` + Whether strict parameter validation is enforced for this function tool. - - `"gpt-4-0125-preview"` + - `type: "function"` - - `"gpt-4-turbo-preview"` + The type of the function tool. Always `function`. - - `"gpt-4-1106-preview"` + - `"function"` - - `"gpt-4-vision-preview"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"gpt-4"` + The tool invocation context(s). - - `"gpt-4-0314"` + - `"direct"` - - `"gpt-4-0613"` + - `"programmatic"` - - `"gpt-4-32k"` + - `defer_loading: optional boolean` - - `"gpt-4-32k-0314"` + Whether this function is deferred and loaded via tool search. - - `"gpt-4-32k-0613"` + - `description: optional string` - - `"gpt-3.5-turbo"` + A description of the function. Used by the model to determine whether or not to call the function. - - `"gpt-3.5-turbo-16k"` + - `output_schema: optional map[unknown]` - - `"gpt-3.5-turbo-0301"` + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `"gpt-3.5-turbo-0613"` + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - - `"gpt-3.5-turbo-1106"` + 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-3.5-turbo-0125"` + - `type: "file_search"` - - `"gpt-3.5-turbo-16k-0613"` + The type of the file search tool. Always `file_search`. -- `description: optional string` + - `"file_search"` - The description of the assistant. The maximum length is 512 characters. + - `vector_store_ids: array of string` -- `instructions: optional string` + The IDs of the vector stores to search. - The system instructions that the assistant uses. The maximum length is 256,000 characters. + - `filters: optional object { key, type, value } or object { filters, type }` -- `metadata: optional Metadata` + 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. -- `name: optional string` + - `key: string` - The name of the assistant. The maximum length is 256 characters. + The key to compare against the value. -- `reasoning_effort: optional ReasoningEffort` + - `type: "eq" or "ne" or "gt" or 5 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. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `"none"` + - `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 - - `"minimal"` + - `"eq"` - - `"low"` + - `"ne"` - - `"medium"` + - `"gt"` - - `"high"` + - `"gte"` - - `"xhigh"` + - `"lt"` - - `"max"` + - `"lte"` -- `response_format: optional AssistantResponseFormatOption` + - `"in"` - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `"nin"` - 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](https://platform.openai.com/docs/guides/structured-outputs). + - `value: string or number or boolean or array of string or number` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + The value to compare against the attribute key; supports string, number, or boolean types. - **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. + - `string` - - `"auto"` + - `number` - `auto` is the default value + - `boolean` - - `"auto"` + - `array of string or number` - - `ResponseFormatText object { type }` + - `string` - Default response format. Used to generate text responses. + - `number` - - `type: "text"` + - `CompoundFilter object { filters, type }` - The type of response format being defined. Always `text`. + Combine multiple filters using `and` or `or`. - - `"text"` + - `filters: array of object { key, type, value } or unknown` - - `ResponseFormatJSONObject object { type }` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - 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. + - `ComparisonFilter object { key, type, value }` - - `type: "json_object"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The type of response format being defined. Always `json_object`. + - `key: string` - - `"json_object"` + The key to compare against the value. - - `ResponseFormatJSONSchema object { json_schema, type }` + - `type: "eq" or "ne" or "gt" or 5 more` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `json_schema: object { name, description, schema, strict }` + - `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 - Structured Outputs configuration options, including a JSON Schema. + - `"eq"` - - `name: string` + - `"ne"` - 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. + - `"gt"` - - `description: optional string` + - `"gte"` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `"lt"` - - `schema: optional map[unknown]` + - `"lte"` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `"in"` - - `strict: optional boolean` + - `"nin"` - 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](https://platform.openai.com/docs/guides/structured-outputs). + - `value: string or number or boolean or array of string or number` - - `type: "json_schema"` + The value to compare against the attribute key; supports string, number, or boolean types. - The type of response format being defined. Always `json_schema`. + - `string` - - `"json_schema"` + - `number` -- `temperature: optional number` + - `boolean` - 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. + - `array of string or number` -- `tool_resources: optional object { code_interpreter, file_search }` + - `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. + - `number` - - `code_interpreter: optional object { file_ids }` + - `unknown` - - `file_ids: optional array of string` + - `type: "and" or "or"` - A list of [file](https://platform.openai.com/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 of operation: `and` or `or`. - - `file_search: optional object { vector_store_ids, vector_stores }` + - `"and"` - - `vector_store_ids: optional array of string` + - `"or"` - The [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. + - `max_num_results: optional number` - - `vector_stores: optional array of object { chunking_strategy, file_ids, metadata }` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - A helper to create a [vector store](https://platform.openai.com/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. + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `chunking_strategy: optional object { type } or object { static, type }` + Ranking options for search. - The chunking strategy used to chunk the file(s). If not set, will use the `auto` strategy. + - `hybrid_search: optional object { embedding_weight, text_weight }` - - `Auto object { type }` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - The default strategy. This strategy currently uses a `max_chunk_size_tokens` of `800` and `chunk_overlap_tokens` of `400`. + - `embedding_weight: number` - - `type: "auto"` + The weight of the embedding in the reciprocal ranking fusion. - Always `auto`. + - `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"` - - `Static object { static, type }` + - `"default-2024-11-15"` - - `static: object { chunk_overlap_tokens, max_chunk_size_tokens }` + - `score_threshold: optional number` - - `chunk_overlap_tokens: number` + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - The number of tokens that overlap between chunks. The default value is `400`. + - `Computer object { type }` - Note that the overlap must not exceed half of `max_chunk_size_tokens`. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `max_chunk_size_tokens: number` + - `type: "computer"` - 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 type of the computer tool. Always `computer`. - - `type: "static"` + - `"computer"` - Always `static`. + - `ComputerUsePreview object { display_height, display_width, environment, type }` - - `"static"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `file_ids: optional array of string` + - `display_height: number` - A list of [file](https://platform.openai.com/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 height of the computer display. - - `metadata: optional Metadata` + - `display_width: 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 width of the computer display. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `environment: "windows" or "mac" or "linux" or 2 more` -- `tools: optional array of AssistantTool` + The type of computer environment to control. - 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`. + - `"windows"` - - `CodeInterpreterTool object { type }` + - `"mac"` - - `type: "code_interpreter"` + - `"linux"` - The type of tool being defined: `code_interpreter` + - `"ubuntu"` - - `"code_interpreter"` + - `"browser"` - - `FileSearchTool object { type, file_search }` + - `type: "computer_use_preview"` - - `type: "file_search"` + The type of the computer use tool. Always `computer_use_preview`. - The type of tool being defined: `file_search` + - `"computer_use_preview"` - - `"file_search"` + - `WebSearch object { type, filters, search_context_size, user_location }` - - `file_search: optional object { max_num_results, ranking_options }` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - Overrides for the file search tool. + - `type: "web_search" or "web_search_2025_08_26"` - - `max_num_results: optional number` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - 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. + - `"web_search"` - Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `"web_search_2025_08_26"` - - `ranking_options: optional object { score_threshold, ranker }` + - `filters: optional object { allowed_domains }` - 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. + Filters for the search. - See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `allowed_domains: optional array of string` - - `score_threshold: number` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - The score threshold for the file search. All values must be a floating point number between 0 and 1. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `ranker: optional "auto" or "default_2024_08_21"` + - `search_context_size: optional "low" or "medium" or "high"` - The ranker to use for the file search. If not specified will use the `auto` ranker. + 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. - - `"auto"` + - `"low"` - - `"default_2024_08_21"` + - `"medium"` - - `FunctionTool object { function, type }` + - `"high"` - - `function: FunctionDefinition` + - `user_location: optional object { city, country, region, 2 more }` - - `name: string` + The approximate location of the user. - 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. + - `city: optional string` - - `description: optional string` + Free text input for the city of the user, e.g. `San Francisco`. - A description of what the function does, used by the model to choose when and how to call the function. + - `country: optional string` - - `parameters: optional FunctionParameters` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + - `region: optional string` - Omitting `parameters` defines a function with an empty parameter list. + Free text input for the region of the user, e.g. `California`. - - `strict: optional boolean` + - `timezone: optional 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](https://platform.openai.com/docs/guides/function-calling). + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `type: "function"` + - `type: optional "approximate"` - The type of tool being defined: `function` + The type of location approximation. Always `approximate`. - - `"function"` + - `"approximate"` -- `top_p: optional number` + - `Mcp object { server_label, type, allowed_callers, 9 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. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - We generally recommend altering this or temperature but not both. + - `server_label: string` -### Returns + A label for this MCP server, used to identify it in tool calls. -- `Assistant object { id, created_at, description, 10 more }` + - `type: "mcp"` - Represents an `assistant` that can call the model and use tools. + The type of the MCP tool. Always `mcp`. - - `id: string` + - `"mcp"` - The identifier, which can be referenced in API endpoints. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `created_at: number` + The tool invocation context(s). - The Unix timestamp (in seconds) for when the assistant was created. + - `"direct"` - - `description: string` + - `"programmatic"` - The description of the assistant. The maximum length is 512 characters. + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `instructions: string` + List of allowed tool names or a filter object. - The system instructions that the assistant uses. The maximum length is 256,000 characters. + - `McpAllowedTools = array of string` - - `metadata: Metadata` + A string array of allowed tool names - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `McpToolFilter object { read_only, tool_names }` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + A filter object to specify which tools are allowed. - - `model: string` + - `read_only: optional boolean` - ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](https://platform.openai.com/docs/models) for descriptions of them. + 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. - - `name: string` + - `tool_names: optional array of string` - The name of the assistant. The maximum length is 256 characters. + List of allowed tool names. - - `object: "assistant"` + - `authorization: optional string` - The object type, which is always `assistant`. + 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. - - `"assistant"` + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `tools: array of AssistantTool` + 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 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`. + Currently supported `connector_id` values are: - - `CodeInterpreterTool object { 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` - - `type: "code_interpreter"` + - `"connector_dropbox"` - The type of tool being defined: `code_interpreter` + - `"connector_gmail"` - - `"code_interpreter"` + - `"connector_googlecalendar"` - - `FileSearchTool object { type, file_search }` + - `"connector_googledrive"` - - `type: "file_search"` + - `"connector_microsoftteams"` - The type of tool being defined: `file_search` + - `"connector_outlookcalendar"` - - `"file_search"` + - `"connector_outlookemail"` - - `file_search: optional object { max_num_results, ranking_options }` + - `"connector_sharepoint"` - Overrides for the file search tool. + - `defer_loading: optional boolean` - - `max_num_results: optional number` + Whether this MCP tool is deferred and discovered via tool search. - 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. + - `headers: optional map[string]` - Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `ranking_options: optional object { score_threshold, ranker }` + - `require_approval: optional object { always, never } or "always" or "never"` - 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. + Specify which of the MCP server's tools require approval. - See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `McpToolApprovalFilter object { always, never }` - - `score_threshold: 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 score threshold for the file search. All values must be a floating point number between 0 and 1. + - `always: optional object { read_only, tool_names }` - - `ranker: optional "auto" or "default_2024_08_21"` + A filter object to specify which tools are allowed. - The ranker to use for the file search. If not specified will use the `auto` ranker. + - `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. - - `"default_2024_08_21"` + - `tool_names: optional array of string` - - `FunctionTool object { function, type }` + List of allowed tool names. - - `function: FunctionDefinition` + - `never: optional object { read_only, tool_names }` - - `name: string` + A filter object to specify which tools are allowed. - 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. + - `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 function does, used by the model to choose when and how to call the function. + - `tool_names: optional array of string` - - `parameters: optional FunctionParameters` + List of allowed tool names. - The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + - `McpToolApprovalSetting = "always" or "never"` - Omitting `parameters` defines a function with an empty parameter list. + 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. - - `strict: optional boolean` + - `"always"` - 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](https://platform.openai.com/docs/guides/function-calling). + - `"never"` - - `type: "function"` + - `server_description: optional string` - The type of tool being defined: `function` + Optional description of the MCP server, used to provide more context. - - `"function"` + - `server_url: optional string` - - `response_format: optional AssistantResponseFormatOption` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `tunnel_id: 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](https://platform.openai.com/docs/guides/structured-outputs). + 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. - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `CodeInterpreter object { container, type, allowed_callers }` - **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 tool that runs Python code to help generate a response to a prompt. - - `"auto"` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - `auto` is the default value + 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` - - `ResponseFormatText object { type }` + The container ID. - Default response format. Used to generate text responses. + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - - `type: "text"` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - The type of response format being defined. Always `text`. + - `type: "auto"` - - `"text"` + Always `auto`. - - `ResponseFormatJSONObject object { type }` + - `"auto"` - 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_ids: optional array of string` - - `type: "json_object"` + An optional list of uploaded files to make available to your code. - The type of response format being defined. Always `json_object`. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `"json_object"` + The memory limit for the code interpreter container. - - `ResponseFormatJSONSchema object { json_schema, type }` + - `"1g"` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `"4g"` - - `json_schema: object { name, description, schema, strict }` + - `"16g"` - Structured Outputs configuration options, including a JSON Schema. + - `"64g"` - - `name: string` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - 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. + Network access policy for the container. - - `description: optional string` + - `BetaContainerNetworkPolicyDisabled object { type }` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `schema: optional map[unknown]` + - `type: "code_interpreter"` - 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 code interpreter tool. Always `code_interpreter`. - - `strict: optional boolean` + - `"code_interpreter"` - 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](https://platform.openai.com/docs/guides/structured-outputs). + - `allowed_callers: optional array of "direct" or "programmatic"` - - `type: "json_schema"` + The tool invocation context(s). - The type of response format being defined. Always `json_schema`. + - `"direct"` - - `"json_schema"` + - `"programmatic"` - - `temperature: optional number` + - `ProgrammaticToolCalling object { type }` - 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. + - `type: "programmatic_tool_calling"` - - `tool_resources: optional object { code_interpreter, file_search }` + The type of the tool. Always `programmatic_tool_calling`. - 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. + - `"programmatic_tool_calling"` - - `code_interpreter: optional object { file_ids }` + - `ImageGeneration object { type, action, background, 9 more }` - - `file_ids: optional array of string` + A tool that generates images using the GPT image models. - A list of [file](https://platform.openai.com/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: "image_generation"` - - `file_search: optional object { vector_store_ids }` + The type of the image generation tool. Always `image_generation`. - - `vector_store_ids: optional array of string` + - `"image_generation"` - The ID of the [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. + - `action: optional "generate" or "edit" or "auto"` - - `top_p: optional number` + Whether to generate a new image or edit an existing image. Default: `auto`. - 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. + - `"generate"` - We generally recommend altering this or temperature but not both. + - `"edit"` -### 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 - }' -``` + - `background: optional "transparent" or "opaque" or "auto"` -#### Response + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. -```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 -} -``` + - `"transparent"` -### Code Interpreter + - `"opaque"` -```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" - }' -``` + - `"auto"` -#### Response + - `input_fidelity: optional "high" or "low"` -```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" -} -``` + 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`. -### Files + - `"high"` -```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" - }' -``` + - `"low"` -#### Response + - `input_image_mask: optional object { file_id, image_url }` -```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" -} -``` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). -## Retrieve assistant + - `file_id: optional string` -**get** `/assistants/{assistant_id}` + File ID for the mask image. -Retrieve assistant + - `image_url: optional string` -### Path Parameters + Base64-encoded mask image. -- `assistant_id: string` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` -### Returns + The image generation model to use. Default: `gpt-image-1`. -- `Assistant object { id, created_at, description, 10 more }` + - `string` - Represents an `assistant` that can call the model and use tools. + - `"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 identifier, which can be referenced in API endpoints. + - `"gpt-image-1"` - - `created_at: number` + - `"gpt-image-1-mini"` - The Unix timestamp (in seconds) for when the assistant was created. + - `"gpt-image-1.5"` - - `description: string` + - `moderation: optional "auto" or "low"` - The description of the assistant. The maximum length is 512 characters. + Moderation level for the generated image. Default: `auto`. - - `instructions: string` + - `"auto"` - The system instructions that the assistant uses. The maximum length is 256,000 characters. + - `"low"` - - `metadata: Metadata` + - `output_compression: 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. + Compression level for the output image. Default: 100. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `output_format: optional "png" or "webp" or "jpeg"` - - `model: string` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](https://platform.openai.com/docs/models) for descriptions of them. + - `"png"` - - `name: string` + - `"webp"` - The name of the assistant. The maximum length is 256 characters. + - `"jpeg"` - - `object: "assistant"` + - `partial_images: optional number` - The object type, which is always `assistant`. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `"assistant"` + - `quality: optional "low" or "medium" or "high" or "auto"` - - `tools: array of AssistantTool` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - 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`. + - `"low"` - - `CodeInterpreterTool object { type }` + - `"medium"` - - `type: "code_interpreter"` + - `"high"` - The type of tool being defined: `code_interpreter` + - `"auto"` - - `"code_interpreter"` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `FileSearchTool object { type, file_search }` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `type: "file_search"` + - `string` - The type of tool being defined: `file_search` + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `"file_search"` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `file_search: optional object { max_num_results, ranking_options }` + - `"1024x1024"` - Overrides for the file search tool. + - `"1024x1536"` - - `max_num_results: optional number` + - `"1536x1024"` - 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. + - `"auto"` - Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `LocalShell object { type }` - - `ranking_options: optional object { score_threshold, ranker }` + A tool that allows the model to execute shell commands in a local environment. - 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: "local_shell"` - See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + The type of the local shell tool. Always `local_shell`. - - `score_threshold: number` + - `"local_shell"` - The score threshold for the file search. All values must be a floating point number between 0 and 1. + - `Shell object { type, allowed_callers, environment }` - - `ranker: optional "auto" or "default_2024_08_21"` + A tool that allows the model to execute shell commands. - The ranker to use for the file search. If not specified will use the `auto` ranker. + - `type: "shell"` - - `"auto"` + The type of the shell tool. Always `shell`. - - `"default_2024_08_21"` + - `"shell"` - - `FunctionTool object { function, type }` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `function: FunctionDefinition` + The tool invocation context(s). - - `name: string` + - `"direct"` - 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"` - - `description: optional string` + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - A description of what the function does, used by the model to choose when and how to call the function. + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - - `parameters: optional FunctionParameters` + - `BetaLocalEnvironment object { type, skills }` - The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + - `BetaContainerReference object { container_id, type }` - Omitting `parameters` defines a function with an empty parameter list. + - `Custom object { name, type, allowed_callers, 3 more }` - - `strict: 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 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](https://platform.openai.com/docs/guides/function-calling). + - `name: string` - - `type: "function"` + The name of the custom tool, used to identify it in tool calls. - The type of tool being defined: `function` + - `type: "custom"` - - `"function"` + The type of the custom tool. Always `custom`. - - `response_format: optional AssistantResponseFormatOption` + - `"custom"` - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `allowed_callers: optional array of "direct" or "programmatic"` - 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](https://platform.openai.com/docs/guides/structured-outputs). + The tool invocation context(s). - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `"direct"` - **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. + - `"programmatic"` - - `"auto"` + - `defer_loading: optional boolean` - `auto` is the default value + Whether this tool should be deferred and discovered via tool search. - - `"auto"` + - `description: optional string` - - `ResponseFormatText object { type }` + Optional description of the custom tool, used to provide more context. - Default response format. Used to generate text responses. + - `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"` - The type of response format being defined. Always `text`. + Unconstrained text format. Always `text`. - `"text"` - - `ResponseFormatJSONObject 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"` - - `ResponseFormatJSONSchema object { json_schema, type }` + The syntax of the grammar definition. One of `lark` or `regex`. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `"lark"` - - `json_schema: object { name, description, schema, strict }` + - `"regex"` - Structured Outputs configuration options, including a JSON Schema. + - `type: "grammar"` - - `name: string` + Grammar format. Always `grammar`. - 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. + - `"grammar"` - - `description: optional string` + - `Namespace object { description, name, tools, type }` - A description of what the response format is for, used by the model to - determine how to respond in the format. + Groups function/custom tools under a shared namespace. - - `schema: optional map[unknown]` + - `description: 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 description of the namespace shown to the model. - - `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](https://platform.openai.com/docs/guides/structured-outputs). + The namespace name used in tool calls (for example, `crm`). - - `type: "json_schema"` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - The type of response format being defined. Always `json_schema`. + The function/custom tools available inside this namespace. - - `"json_schema"` + - `Function object { name, type, allowed_callers, 5 more }` - - `temperature: optional number` + - `name: 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. + - `type: "function"` - - `tool_resources: optional object { code_interpreter, file_search }` + - `"function"` - 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. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `code_interpreter: optional object { file_ids }` + The tool invocation context(s). - - `file_ids: optional array of string` + - `"direct"` - A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter`` tool. There can be a maximum of 20 files associated with the tool. + - `"programmatic"` - - `file_search: optional object { vector_store_ids }` + - `defer_loading: optional boolean` - - `vector_store_ids: optional array of string` + Whether this function should be deferred and discovered via tool search. - The ID of the [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. + - `description: optional string` - - `top_p: optional number` + - `output_schema: optional map[unknown]` - 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 JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - We generally recommend altering this or temperature but not both. + - `parameters: optional unknown` -### Example + - `strict: optional boolean` -```http -curl https://api.openai.com/v1/assistants/$ASSISTANT_ID \ - -H 'OpenAI-Beta: assistants=v2' \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + 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. -#### Response + - `Custom object { name, type, allowed_callers, 3 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 -} -``` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) -### Example + - `name: 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" -``` + The name of the custom tool, used to identify it in tool calls. -#### Response + - `type: "custom"` -```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" -} -``` + The type of the custom tool. Always `custom`. -## Modify assistant + - `"custom"` -**post** `/assistants/{assistant_id}` + - `allowed_callers: optional array of "direct" or "programmatic"` -Modify assistant + The tool invocation context(s). -### Path Parameters + - `"direct"` -- `assistant_id: string` + - `"programmatic"` -### Body Parameters + - `defer_loading: optional boolean` -- `description: optional string` + Whether this tool should be deferred and discovered via tool search. - The description of the assistant. The maximum length is 512 characters. + - `description: optional string` -- `instructions: optional string` + Optional description of the custom tool, used to provide more context. - The system instructions that the assistant uses. The maximum length is 256,000 characters. + - `format: optional object { type } or object { definition, syntax, type }` -- `metadata: optional Metadata` + The input format for the custom tool. Default is unconstrained text. - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `Text object { type }` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + Unconstrained free-form text. -- `model: optional string or "gpt-5" or "gpt-5-mini" or "gpt-5-nano" or 39 more` + - `type: "text"` - ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](https://platform.openai.com/docs/models) for descriptions of them. + Unconstrained text format. Always `text`. - - `string` + - `"text"` - - `AssistantSupportedModels = "gpt-5" or "gpt-5-mini" or "gpt-5-nano" or 39 more` + - `Grammar object { definition, syntax, type }` - ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](https://platform.openai.com/docs/models) for descriptions of them. + A grammar defined by the user. - - `"gpt-5"` + - `definition: string` - - `"gpt-5-mini"` + The grammar definition. - - `"gpt-5-nano"` + - `syntax: "lark" or "regex"` - - `"gpt-5-2025-08-07"` + The syntax of the grammar definition. One of `lark` or `regex`. - - `"gpt-5-mini-2025-08-07"` + - `"lark"` - - `"gpt-5-nano-2025-08-07"` + - `"regex"` - - `"gpt-4.1"` + - `type: "grammar"` - - `"gpt-4.1-mini"` + Grammar format. Always `grammar`. - - `"gpt-4.1-nano"` + - `"grammar"` - - `"gpt-4.1-2025-04-14"` + - `type: "namespace"` - - `"gpt-4.1-mini-2025-04-14"` + The type of the tool. Always `namespace`. - - `"gpt-4.1-nano-2025-04-14"` + - `"namespace"` - - `"o3-mini"` + - `ToolSearch object { type, description, execution, parameters }` - - `"o3-mini-2025-01-31"` + Hosted or BYOT tool search configuration for deferred tools. - - `"o1"` + - `type: "tool_search"` - - `"o1-2024-12-17"` + The type of the tool. Always `tool_search`. - - `"gpt-4o"` + - `"tool_search"` - - `"gpt-4o-2024-11-20"` + - `description: optional string` - - `"gpt-4o-2024-08-06"` + Description shown to the model for a client-executed tool search tool. - - `"gpt-4o-2024-05-13"` + - `execution: optional "server" or "client"` - - `"gpt-4o-mini"` + Whether tool search is executed by the server or by the client. - - `"gpt-4o-mini-2024-07-18"` + - `"server"` - - `"gpt-4.5-preview"` + - `"client"` - - `"gpt-4.5-preview-2025-02-27"` + - `parameters: optional unknown` - - `"gpt-4-turbo"` + Parameter schema for a client-executed tool search tool. - - `"gpt-4-turbo-2024-04-09"` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - - `"gpt-4-0125-preview"` + 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). - - `"gpt-4-turbo-preview"` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `"gpt-4-1106-preview"` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `"gpt-4-vision-preview"` + - `"web_search_preview"` - - `"gpt-4"` + - `"web_search_preview_2025_03_11"` - - `"gpt-4-0314"` + - `search_content_types: optional array of "text" or "image"` - - `"gpt-4-0613"` + - `"text"` - - `"gpt-4-32k"` + - `"image"` - - `"gpt-4-32k-0314"` + - `search_context_size: optional "low" or "medium" or "high"` - - `"gpt-4-32k-0613"` + 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-3.5-turbo"` + - `"low"` - - `"gpt-3.5-turbo-16k"` + - `"medium"` - - `"gpt-3.5-turbo-0613"` + - `"high"` - - `"gpt-3.5-turbo-1106"` + - `user_location: optional object { type, city, country, 2 more }` - - `"gpt-3.5-turbo-0125"` + The user's location. - - `"gpt-3.5-turbo-16k-0613"` + - `type: "approximate"` -- `name: optional string` + The type of location approximation. Always `approximate`. - The name of the assistant. The maximum length is 256 characters. + - `"approximate"` -- `reasoning_effort: optional ReasoningEffort` + - `city: 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. + Free text input for the city of the user, e.g. `San Francisco`. - - `"none"` + - `country: optional string` - - `"minimal"` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `"low"` + - `region: optional string` - - `"medium"` + Free text input for the region of the user, e.g. `California`. - - `"high"` + - `timezone: optional string` - - `"xhigh"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `"max"` + - `ApplyPatch object { type, allowed_callers }` -- `response_format: optional AssistantResponseFormatOption` + Allows the assistant to create, delete, or update files using unified diffs. - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `type: "apply_patch"` - 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](https://platform.openai.com/docs/guides/structured-outputs). + The type of the tool. Always `apply_patch`. - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `"apply_patch"` - **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_callers: optional array of "direct" or "programmatic"` - - `"auto"` + The tool invocation context(s). - `auto` is the default value + - `"direct"` - - `"auto"` + - `"programmatic"` - - `ResponseFormatText object { type }` + - `type: "additional_tools"` - Default response format. Used to generate text responses. + The item type. Always `additional_tools`. - - `type: "text"` + - `"additional_tools"` - The type of response format being defined. Always `text`. + - `id: optional string` - - `"text"` + The unique ID of this additional tools 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"` + - `Reasoning object { id, summary, type, 4 more }` - - `ResponseFormatJSONSchema object { json_schema, 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). - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `id: string` - - `json_schema: object { name, description, schema, strict }` + The unique identifier of the reasoning content. - Structured Outputs configuration options, including a JSON Schema. + - `summary: array of object { text, type }` - - `name: string` + Reasoning summary content. - 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: string` - - `description: optional string` + A summary of the reasoning output from the model so far. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `type: "summary_text"` - - `schema: optional map[unknown]` + The type of the object. Always `summary_text`. - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `"summary_text"` - - `strict: optional boolean` + - `type: "reasoning"` - 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](https://platform.openai.com/docs/guides/structured-outputs). + The type of the object. Always `reasoning`. - - `type: "json_schema"` + - `"reasoning"` - The type of response format being defined. Always `json_schema`. + - `agent: optional object { agent_name }` - - `"json_schema"` + The agent that produced this item. -- `temperature: optional number` + - `agent_name: 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 canonical name of the agent that produced this item. -- `tool_resources: optional object { code_interpreter, file_search }` + - `content: optional array of object { text, 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. + Reasoning text content. - - `code_interpreter: optional object { file_ids }` + - `text: string` - - `file_ids: optional array of string` + The reasoning text from the model. - Overrides the list of [file](https://platform.openai.com/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: "reasoning_text"` - - `file_search: optional object { vector_store_ids }` + The type of the reasoning text. Always `reasoning_text`. - - `vector_store_ids: optional array of string` + - `"reasoning_text"` - Overrides the [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. + - `encrypted_content: optional string` -- `tools: optional array of AssistantTool` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - 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`. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `CodeInterpreterTool object { type }` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `type: "code_interpreter"` + - `"in_progress"` - The type of tool being defined: `code_interpreter` + - `"completed"` - - `"code_interpreter"` + - `"incomplete"` - - `FileSearchTool object { type, file_search }` + - `Compaction object { encrypted_content, type, id, agent }` - - `type: "file_search"` + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). - The type of tool being defined: `file_search` + - `encrypted_content: string` - - `"file_search"` + The encrypted content of the compaction summary. - - `file_search: optional object { max_num_results, ranking_options }` + - `type: "compaction"` - Overrides for the file search tool. + The type of the item. Always `compaction`. - - `max_num_results: optional number` + - `"compaction"` - 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](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + The ID of the compaction item. - - `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](https://platform.openai.com/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. + - `ImageGenerationCall object { id, result, status, 2 more }` - - `ranker: optional "auto" or "default_2024_08_21"` + An image generation request made by the model. - The ranker to use for the file search. If not specified will use the `auto` ranker. + - `id: string` - - `"auto"` + The unique ID of the image generation call. - - `"default_2024_08_21"` + - `result: string` - - `FunctionTool object { function, type }` + The generated image encoded in base64. - - `function: FunctionDefinition` + - `status: "in_progress" or "completed" or "generating" or "failed"` - - `name: string` + The status of the image generation 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. + - `"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. + - `"generating"` - - `parameters: optional FunctionParameters` + - `"failed"` - The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + - `type: "image_generation_call"` - Omitting `parameters` defines a function with an empty parameter list. + The type of the image generation call. Always `image_generation_call`. - - `strict: optional boolean` + - `"image_generation_call"` - 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](https://platform.openai.com/docs/guides/function-calling). + - `agent: optional object { agent_name }` - - `type: "function"` + The agent that produced this item. - The type of tool being defined: `function` + - `agent_name: string` - - `"function"` + The canonical name of the agent that produced this item. -- `top_p: optional number` + - `CodeInterpreterCall object { id, code, container_id, 4 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. + A tool call to run code. - We generally recommend altering this or temperature but not both. + - `id: string` -### Returns + The unique ID of the code interpreter tool call. -- `Assistant object { id, created_at, description, 10 more }` + - `code: string` - Represents an `assistant` that can call the model and use tools. + The code to run, or null if not available. - - `id: string` + - `container_id: string` - The identifier, which can be referenced in API endpoints. + The ID of the container used to run the code. - - `created_at: number` + - `outputs: array of object { logs, type } or object { type, url }` - The Unix timestamp (in seconds) for when the assistant was created. + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `description: string` + - `Logs object { logs, type }` - The description of the assistant. The maximum length is 512 characters. + The logs output from the code interpreter. - - `instructions: string` + - `logs: string` - The system instructions that the assistant uses. The maximum length is 256,000 characters. + The logs output from the code interpreter. - - `metadata: Metadata` + - `type: "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. + The type of the output. Always `logs`. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `"logs"` - - `model: string` + - `Image object { type, url }` - ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](https://platform.openai.com/docs/models) for descriptions of them. + The image output from the code interpreter. - - `name: string` + - `type: "image"` - The name of the assistant. The maximum length is 256 characters. + The type of the output. Always `image`. - - `object: "assistant"` + - `"image"` - The object type, which is always `assistant`. + - `url: string` - - `"assistant"` + The URL of the image output from the code interpreter. - - `tools: array of AssistantTool` + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - 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 status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `CodeInterpreterTool object { type }` + - `"in_progress"` - - `type: "code_interpreter"` + - `"completed"` - The type of tool being defined: `code_interpreter` + - `"incomplete"` - - `"code_interpreter"` + - `"interpreting"` - - `FileSearchTool object { type, file_search }` + - `"failed"` - - `type: "file_search"` + - `type: "code_interpreter_call"` - The type of tool being defined: `file_search` + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `"file_search"` + - `"code_interpreter_call"` - - `file_search: optional object { max_num_results, ranking_options }` + - `agent: optional object { agent_name }` - Overrides for the file search tool. + The agent that produced this item. - - `max_num_results: optional number` + - `agent_name: 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 canonical name of the agent that produced this item. - Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `LocalShellCall object { id, action, call_id, 3 more }` - - `ranking_options: optional object { score_threshold, ranker }` + A tool call to run a command on the local shell. - 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. + - `id: string` - See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + The unique ID of the local shell call. - - `score_threshold: number` + - `action: object { command, env, type, 3 more }` - The score threshold for the file search. All values must be a floating point number between 0 and 1. + Execute a shell command on the server. - - `ranker: optional "auto" or "default_2024_08_21"` + - `command: array of string` - The ranker to use for the file search. If not specified will use the `auto` ranker. + The command to run. - - `"auto"` + - `env: map[string]` - - `"default_2024_08_21"` + Environment variables to set for the command. - - `FunctionTool object { function, type }` + - `type: "exec"` - - `function: FunctionDefinition` + The type of the local shell action. Always `exec`. - - `name: string` + - `"exec"` - 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. + - `timeout_ms: optional number` - - `description: optional string` + Optional timeout in milliseconds for the command. - A description of what the function does, used by the model to choose when and how to call the function. + - `user: optional string` - - `parameters: optional FunctionParameters` + Optional user to run the command as. - The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + - `working_directory: optional string` - Omitting `parameters` defines a function with an empty parameter list. + Optional working directory to run the command in. - - `strict: optional boolean` + - `call_id: 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](https://platform.openai.com/docs/guides/function-calling). + The unique ID of the local shell tool call generated by the model. - - `type: "function"` + - `status: "in_progress" or "completed" or "incomplete"` - The type of tool being defined: `function` + The status of the local shell call. - - `"function"` + - `"in_progress"` - - `response_format: optional AssistantResponseFormatOption` + - `"completed"` - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `"incomplete"` - 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](https://platform.openai.com/docs/guides/structured-outputs). + - `type: "local_shell_call"` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + The type of the local shell call. Always `local_shell_call`. - **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. + - `"local_shell_call"` - - `"auto"` + - `agent: optional object { agent_name }` - `auto` is the default value + The agent that produced this item. - - `"auto"` + - `agent_name: string` - - `ResponseFormatText object { type }` + The canonical name of the agent that produced this item. - Default response format. Used to generate text responses. + - `LocalShellCallOutput object { id, output, type, 2 more }` - - `type: "text"` + The output of a local shell tool call. - The type of response format being defined. Always `text`. + - `id: string` - - `"text"` + The unique ID of the local shell tool call generated by the model. - - `ResponseFormatJSONObject object { type }` + - `output: 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. + A JSON string of the output of the local shell tool call. - - `type: "json_object"` + - `type: "local_shell_call_output"` - The type of response format being defined. Always `json_object`. + The type of the local shell tool call output. Always `local_shell_call_output`. - - `"json_object"` + - `"local_shell_call_output"` - - `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](https://platform.openai.com/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` + - `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`. - - `description: optional string` + - `"in_progress"` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `"completed"` - - `schema: optional map[unknown]` + - `"incomplete"` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `ShellCall object { action, call_id, type, 5 more }` - - `strict: optional boolean` + A tool representing a request to execute one or more shell commands. - 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](https://platform.openai.com/docs/guides/structured-outputs). + - `action: object { commands, max_output_length, timeout_ms }` - - `type: "json_schema"` + The shell commands and limits that describe how to run the tool call. - The type of response format being defined. Always `json_schema`. + - `commands: array of string` - - `"json_schema"` + Ordered shell commands for the execution environment to run. - - `temperature: optional number` + - `max_output_length: optional 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. + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - - `tool_resources: optional object { code_interpreter, file_search }` + - `timeout_ms: optional 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. + Maximum wall-clock time in milliseconds to allow the shell commands to run. - - `code_interpreter: optional object { file_ids }` + - `call_id: string` - - `file_ids: optional array of string` + The unique ID of the shell tool call generated by the model. - A list of [file](https://platform.openai.com/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: "shell_call"` - - `file_search: optional object { vector_store_ids }` + The type of the item. Always `shell_call`. - - `vector_store_ids: optional array of string` + - `"shell_call"` - The ID of the [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. + - `id: optional string` - - `top_p: optional number` + The unique ID of the shell tool call. Populated when this item is returned via API. - An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. + - `agent: optional object { agent_name }` - We generally recommend altering this or temperature but not both. + The agent that produced this item. -### Example + - `agent_name: 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 canonical name of the agent that produced this item. -#### Response + - `caller: optional object { type } or object { caller_id, type }` -```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 execution context that produced this tool call. -### Example + - `Direct object { type }` -```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" - }' -``` + - `type: "direct"` -#### Response + The caller type. Always `direct`. -```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" -} -``` + - `"direct"` -## Delete assistant + - `Program object { caller_id, type }` -**delete** `/assistants/{assistant_id}` + - `caller_id: string` -Delete assistant + The call ID of the program item that produced this tool call. -### Path Parameters + - `type: "program"` -- `assistant_id: string` + The caller type. Always `program`. -### Returns + - `"program"` -- `AssistantDeleted object { id, deleted, object }` + - `environment: optional BetaLocalEnvironment or BetaContainerReference` - - `id: string` + The environment to execute the shell commands in. - - `deleted: boolean` + - `BetaLocalEnvironment object { type, skills }` - - `object: "assistant.deleted"` + - `BetaContainerReference object { container_id, type }` - - `"assistant.deleted"` + - `status: optional "in_progress" or "completed" or "incomplete"` -### Example + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. -```http -curl https://api.openai.com/v1/assistants/$ASSISTANT_ID \ - -X DELETE \ - -H 'OpenAI-Beta: assistants=v2' \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + - `"in_progress"` -#### Response + - `"completed"` -```json -{ - "id": "id", - "deleted": true, - "object": "assistant.deleted" -} -``` + - `"incomplete"` -### Example + - `ShellCallOutput object { call_id, output, type, 5 more }` -```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 streamed output items emitted by a shell tool call. -#### Response + - `call_id: string` -```json -{ - "id": "asst_abc123", - "object": "assistant.deleted", - "deleted": true -} -``` + The unique ID of the shell tool call generated by the model. -## Domain Types + - `output: array of BetaResponseFunctionShellCallOutputContent` -### Assistant + Captured chunks of stdout and stderr output, along with their associated outcomes. -- `Assistant object { id, created_at, description, 10 more }` + - `outcome: object { type } or object { exit_code, type }` - Represents an `assistant` that can call the model and use tools. + The exit or timeout outcome associated with this shell call. - - `id: string` + - `Timeout object { type }` - The identifier, which can be referenced in API endpoints. + Indicates that the shell call exceeded its configured time limit. - - `created_at: number` + - `type: "timeout"` - The Unix timestamp (in seconds) for when the assistant was created. + The outcome type. Always `timeout`. - - `description: string` + - `"timeout"` - The description of the assistant. The maximum length is 512 characters. + - `Exit object { exit_code, type }` - - `instructions: string` + Indicates that the shell commands finished and returned an exit code. - The system instructions that the assistant uses. The maximum length is 256,000 characters. + - `exit_code: number` - - `metadata: Metadata` + The exit code returned by the shell process. - 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: "exit"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The outcome type. Always `exit`. - - `model: string` + - `"exit"` - ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](https://platform.openai.com/docs/models) for descriptions of them. + - `stderr: string` - - `name: string` + Captured stderr output for the shell call. - The name of the assistant. The maximum length is 256 characters. + - `stdout: string` - - `object: "assistant"` + Captured stdout output for the shell call. - The object type, which is always `assistant`. + - `type: "shell_call_output"` - - `"assistant"` + The type of the item. Always `shell_call_output`. - - `tools: array of AssistantTool` + - `"shell_call_output"` - 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`. + - `id: optional string` - - `CodeInterpreterTool object { type }` + The unique ID of the shell tool call output. Populated when this item is returned via API. - - `type: "code_interpreter"` + - `agent: optional object { agent_name }` - The type of tool being defined: `code_interpreter` + The agent that produced this item. - - `"code_interpreter"` + - `agent_name: string` - - `FileSearchTool object { type, file_search }` + The canonical name of the agent that produced this item. - - `type: "file_search"` + - `caller: optional object { type } or object { caller_id, type }` - The type of tool being defined: `file_search` + The execution context that produced this tool call. - - `"file_search"` + - `Direct object { type }` - - `file_search: optional object { max_num_results, ranking_options }` + - `type: "direct"` - Overrides for the file search tool. + The caller type. Always `direct`. - - `max_num_results: optional number` + - `"direct"` - 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. + - `Program object { caller_id, type }` - Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `caller_id: string` - - `ranking_options: optional object { score_threshold, ranker }` + The call ID of the program item that produced this 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. + - `type: "program"` - See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + The caller type. Always `program`. - - `score_threshold: number` + - `"program"` - The score threshold for the file search. All values must be a floating point number between 0 and 1. + - `max_output_length: optional number` - - `ranker: optional "auto" or "default_2024_08_21"` + The maximum number of UTF-8 characters captured for this shell call's combined output. - The ranker to use for the file search. If not specified will use the `auto` ranker. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"auto"` + The status of the shell call output. - - `"default_2024_08_21"` + - `"in_progress"` - - `FunctionTool object { function, type }` + - `"completed"` - - `function: FunctionDefinition` + - `"incomplete"` - - `name: string` + - `ApplyPatchCall object { call_id, operation, status, 4 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. + A tool call representing a request to create, delete, or update files using diff patches. - - `description: optional string` + - `call_id: string` - A description of what the function does, used by the model to choose when and how to call the function. + The unique ID of the apply patch tool call generated by the model. - - `parameters: optional FunctionParameters` + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + The specific create, delete, or update instruction for the apply_patch tool call. - Omitting `parameters` defines a function with an empty parameter list. + - `CreateFile object { diff, path, type }` - - `strict: optional boolean` + Instruction for creating a new file via the apply_patch tool. - 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](https://platform.openai.com/docs/guides/function-calling). + - `diff: string` - - `type: "function"` + Unified diff content to apply when creating the file. - The type of tool being defined: `function` + - `path: string` - - `"function"` + Path of the file to create relative to the workspace root. - - `response_format: optional AssistantResponseFormatOption` + - `type: "create_file"` - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + The operation type. Always `create_file`. - 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](https://platform.openai.com/docs/guides/structured-outputs). + - `"create_file"` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `DeleteFile object { path, type }` - **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. + Instruction for deleting an existing file via the apply_patch tool. - - `"auto"` + - `path: string` - `auto` is the default value + Path of the file to delete relative to the workspace root. - - `"auto"` + - `type: "delete_file"` - - `ResponseFormatText object { type }` + The operation type. Always `delete_file`. - Default response format. Used to generate text responses. + - `"delete_file"` - - `type: "text"` + - `UpdateFile object { diff, path, type }` - The type of response format being defined. Always `text`. + Instruction for updating an existing file via the apply_patch tool. - - `"text"` + - `diff: string` - - `ResponseFormatJSONObject object { type }` + Unified diff content to apply to the existing 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. + - `path: string` - - `type: "json_object"` + Path of the file to update relative to the workspace root. - The type of response format being defined. Always `json_object`. + - `type: "update_file"` - - `"json_object"` + The operation type. Always `update_file`. - - `ResponseFormatJSONSchema object { json_schema, type }` + - `"update_file"` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `status: "in_progress" or "completed"` - - `json_schema: object { name, description, schema, strict }` + The status of the apply patch tool call. One of `in_progress` or `completed`. - Structured Outputs configuration options, including a JSON Schema. + - `"in_progress"` - - `name: string` + - `"completed"` - 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"` - - `description: optional string` + The type of the item. Always `apply_patch_call`. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `"apply_patch_call"` - - `schema: optional map[unknown]` + - `id: 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 unique ID of the apply patch tool call. Populated when this item is returned via API. - - `strict: optional boolean` + - `agent: optional object { agent_name }` - 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](https://platform.openai.com/docs/guides/structured-outputs). + The agent that produced this item. - - `type: "json_schema"` + - `agent_name: string` - The type of response format being defined. Always `json_schema`. + The canonical name of the agent that produced this item. - - `"json_schema"` + - `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. + - `Direct object { type }` - - `tool_resources: optional object { code_interpreter, file_search }` + - `type: "direct"` - 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 caller type. Always `direct`. - - `code_interpreter: optional object { file_ids }` + - `"direct"` - - `file_ids: optional array of string` + - `Program object { caller_id, type }` - A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter`` tool. There can be a maximum of 20 files associated with the tool. + - `caller_id: string` - - `file_search: optional object { vector_store_ids }` + The call ID of the program item that produced this tool call. - - `vector_store_ids: optional array of string` + - `type: "program"` - The ID of the [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. + The caller type. Always `program`. - - `top_p: optional number` + - `"program"` - 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. + - `ApplyPatchCallOutput object { call_id, status, type, 4 more }` - We generally recommend altering this or temperature but not both. + The streamed output emitted by an apply patch tool call. -### Assistant Deleted + - `call_id: string` -- `AssistantDeleted object { id, deleted, object }` + The unique ID of the apply patch tool call generated by the model. - - `id: string` + - `status: "completed" or "failed"` - - `deleted: boolean` + The status of the apply patch tool call output. One of `completed` or `failed`. - - `object: "assistant.deleted"` + - `"completed"` - - `"assistant.deleted"` + - `"failed"` -### Assistant Stream Event + - `type: "apply_patch_call_output"` -- `AssistantStreamEvent = object { data, event, enabled } or object { data, event } or object { data, event } or 21 more` + The type of the item. Always `apply_patch_call_output`. - Represents an event emitted when streaming a Run. + - `"apply_patch_call_output"` - Each event in a server-sent events stream has an `event` and `data` property: + - `id: optional string` - ``` - event: thread.created - data: {"id": "thread_123", "object": "thread", ...} - ``` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - 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. + - `agent: optional object { agent_name }` - We may add additional events over time, so we recommend handling unknown events gracefully - in your code. See the [Assistants API quickstart](https://platform.openai.com/docs/assistants/overview) to learn how to - integrate the Assistants API with streaming. + The agent that produced this item. - - `ThreadCreated object { data, event, enabled }` + - `agent_name: string` - Occurs when a new [thread](https://platform.openai.com/docs/api-reference/threads/object) is created. + The canonical name of the agent that produced this item. - - `data: Thread` + - `caller: optional object { type } or object { caller_id, type }` - Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). + The execution context that produced this tool call. - - `id: string` + - `Direct object { type }` - The identifier, which can be referenced in API endpoints. + - `type: "direct"` - - `created_at: number` + The caller type. Always `direct`. - The Unix timestamp (in seconds) for when the thread was created. + - `"direct"` - - `metadata: Metadata` + - `Program object { caller_id, 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. + - `caller_id: string` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The call ID of the program item that produced this tool call. - - `object: "thread"` + - `type: "program"` - The object type, which is always `thread`. + The caller type. Always `program`. - - `"thread"` + - `"program"` - - `tool_resources: object { code_interpreter, file_search }` + - `output: optional string` - 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. - - - `code_interpreter: optional object { file_ids }` - - - `file_ids: optional array of string` - - A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. - - - `file_search: optional object { vector_store_ids }` + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - - `vector_store_ids: optional array of string` + - `McpListTools object { id, server_label, tools, 3 more }` - The [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this thread. There can be a maximum of 1 vector store attached to the thread. + A list of tools available on an MCP server. - - `event: "thread.created"` + - `id: string` - - `"thread.created"` + The unique ID of the list. - - `enabled: optional boolean` + - `server_label: string` - Whether to enable input audio transcription. + The label of the MCP server. - - `ThreadRunCreated object { data, event }` + - `tools: array of object { input_schema, name, annotations, description }` - Occurs when a new [run](https://platform.openai.com/docs/api-reference/runs/object) is created. + The tools available on the server. - - `data: Run` + - `input_schema: unknown` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + The JSON schema describing the tool's input. - - `id: string` + - `name: string` - The identifier, which can be referenced in API endpoints. + The name of the tool. - - `assistant_id: string` + - `annotations: optional unknown` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + Additional annotations about the tool. - - `cancelled_at: number` + - `description: optional string` - The Unix timestamp (in seconds) for when the run was cancelled. + The description of the tool. - - `completed_at: number` + - `type: "mcp_list_tools"` - The Unix timestamp (in seconds) for when the run was completed. + The type of the item. Always `mcp_list_tools`. - - `created_at: number` + - `"mcp_list_tools"` - The Unix timestamp (in seconds) for when the run was created. + - `agent: optional object { agent_name }` - - `expires_at: number` + The agent that produced this item. - The Unix timestamp (in seconds) for when the run will expire. + - `agent_name: string` - - `failed_at: number` + The canonical name of the agent that produced this item. - The Unix timestamp (in seconds) for when the run failed. + - `error: optional string` - - `incomplete_details: object { reason }` + Error message if the server could not list tools. - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + - `McpApprovalRequest object { id, arguments, name, 3 more }` - - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` + A request for human approval of a tool invocation. - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + - `id: string` - - `"max_completion_tokens"` + The unique ID of the approval request. - - `"max_prompt_tokens"` + - `arguments: string` - - `instructions: string` + A JSON string of arguments for the tool. - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `name: string` - - `last_error: object { code, message }` + The name of the tool to run. - The last error associated with this run. Will be `null` if there are no errors. + - `server_label: string` - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` + The label of the MCP server making the request. - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + - `type: "mcp_approval_request"` - - `"server_error"` + The type of the item. Always `mcp_approval_request`. - - `"rate_limit_exceeded"` + - `"mcp_approval_request"` - - `"invalid_prompt"` + - `agent: optional object { agent_name }` - - `message: string` + The agent that produced this item. - A human-readable description of the error. + - `agent_name: string` - - `max_completion_tokens: number` + The canonical name of the agent that produced this item. - The maximum number of completion tokens specified to have been used over the course of the run. + - `McpApprovalResponse object { approval_request_id, approve, type, 3 more }` - - `max_prompt_tokens: number` + A response to an MCP approval request. - The maximum number of prompt tokens specified to have been used over the course of the run. + - `approval_request_id: string` - - `metadata: Metadata` + The ID of the approval request being answered. - 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. + - `approve: boolean` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + Whether the request was approved. - - `model: string` + - `type: "mcp_approval_response"` - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + The type of the item. Always `mcp_approval_response`. - - `object: "thread.run"` + - `"mcp_approval_response"` - The object type, which is always `thread.run`. + - `id: optional string` - - `"thread.run"` + The unique ID of the approval response - - `parallel_tool_calls: boolean` + - `agent: optional object { agent_name }` - Whether to enable [parallel function calling](https://platform.openai.com/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 }` + - `reason: optional string` - Details on the tool outputs needed for this run to continue. + Optional reason for the decision. - - `tool_calls: array of RequiredActionFunctionToolCall` + - `McpCall object { id, arguments, name, 7 more }` - A list of the relevant tool calls. + An invocation of a tool on an MCP server. - `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](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. - - - `function: object { arguments, name }` - - The function definition. + The unique ID of the tool call. - `arguments: string` - The arguments that the model expects you to pass to the function. + A JSON string of the arguments passed to the tool. - `name: string` - The name of the function. + The name of the tool that was run. - - `type: "function"` + - `server_label: string` - The type of tool call the output is required for. For now, this is always `function`. + The label of the MCP server running the tool. - - `"function"` + - `type: "mcp_call"` - - `type: "submit_tool_outputs"` + The type of the item. Always `mcp_call`. - For now, this is always `submit_tool_outputs`. + - `"mcp_call"` - - `"submit_tool_outputs"` + - `agent: optional object { agent_name }` - - `response_format: AssistantResponseFormatOption` + The agent that produced this item. - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `agent_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](https://platform.openai.com/docs/guides/structured-outputs). + The canonical name of the agent that produced this item. - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `approval_request_id: optional 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. + 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` - `auto` is the default value + The error from the tool call, if any. - - `"auto"` + - `output: optional string` - - `ResponseFormatText object { type }` + The output from the tool call. - Default response format. Used to generate text responses. + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - - `type: "text"` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - The type of response format being defined. Always `text`. + - `"in_progress"` - - `"text"` + - `"completed"` - - `ResponseFormatJSONObject object { type }` + - `"incomplete"` - 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. + - `"calling"` - - `type: "json_object"` + - `"failed"` - The type of response format being defined. Always `json_object`. + - `CustomToolCallOutput object { call_id, output, type, 3 more }` - - `"json_object"` + The output of a custom tool call from your code, being sent back to the model. - - `ResponseFormatJSONSchema object { json_schema, type }` + - `call_id: string` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + The call ID, used to map this custom tool call output to a custom tool call. - - `json_schema: object { name, description, schema, strict }` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - Structured Outputs configuration options, including a JSON Schema. + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `name: string` + - `StringOutput = string` - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + A string of the output of the custom tool call. - - `description: optional string` + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - A description of what the response format is for, used by the model to - determine how to respond in the format. + Text, image, or file output of the custom tool call. - - `schema: optional map[unknown]` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + A text input to the model. - - `strict: optional boolean` + - `BetaResponseInputImage object { detail, type, file_id, 2 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](https://platform.openai.com/docs/guides/structured-outputs). + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `type: "json_schema"` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - The type of response format being defined. Always `json_schema`. + A file input to the model. - - `"json_schema"` + - `type: "custom_tool_call_output"` - - `started_at: number` + The type of the custom tool call output. Always `custom_tool_call_output`. - The Unix timestamp (in seconds) for when the run was started. + - `"custom_tool_call_output"` - - `status: RunStatus` + - `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 unique ID of the custom tool call output in the OpenAI platform. - - `"queued"` + - `agent: optional object { agent_name }` - - `"in_progress"` + The agent that produced this item. - - `"requires_action"` + - `agent_name: string` - - `"cancelling"` + The canonical name of the agent that produced this item. - - `"cancelled"` + - `caller: optional object { type } or object { caller_id, type }` - - `"failed"` + The execution context that produced this tool call. - - `"completed"` + - `Direct object { type }` - - `"incomplete"` + - `type: "direct"` - - `"expired"` + The caller type. Always `direct`. - - `thread_id: string` + - `"direct"` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + - `Program object { caller_id, type }` - - `tool_choice: AssistantToolChoiceOption` + - `caller_id: 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. + The call ID of the program item that produced this tool call. - - `Auto = "none" or "auto" or "required"` + - `type: "program"` - `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 caller type. Always `program`. - - `"none"` + - `"program"` - - `"auto"` + - `CustomToolCall object { call_id, input, name, 5 more }` - - `"required"` + A call to a custom tool created by the model. - - `AssistantToolChoice object { type, function }` + - `call_id: string` - Specifies a tool the model should use. Use to force the model to call a specific tool. + An identifier used to map this custom tool call to a tool call output. - - `type: "function" or "code_interpreter" or "file_search"` + - `input: string` - The type of the tool. If type is `function`, the function name must be set + The input for the custom tool call generated by the model. - - `"function"` + - `name: string` - - `"code_interpreter"` + The name of the custom tool being called. - - `"file_search"` + - `type: "custom_tool_call"` - - `function: optional AssistantToolChoiceFunction` + The type of the custom tool call. Always `custom_tool_call`. - - `name: string` + - `"custom_tool_call"` - The name of the function to call. + - `id: optional string` - - `tools: array of AssistantTool` + The unique ID of the custom tool call in the OpenAI platform. - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `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"` + - `caller: optional object { type } or object { caller_id, type }` - - `FileSearchTool object { type, file_search }` + The execution context that produced this tool call. - - `type: "file_search"` + - `Direct object { type }` - The type of tool being defined: `file_search` + - `type: "direct"` - - `"file_search"` + - `"direct"` - - `file_search: optional object { max_num_results, ranking_options }` + - `Program object { caller_id, type }` - Overrides for the file search tool. + - `caller_id: string` - - `max_num_results: optional number` + The call ID of the program item that produced this tool call. - 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: "program"` - Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `"program"` - - `ranking_options: optional object { score_threshold, ranker }` + - `namespace: optional 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 namespace of the custom tool being called. - See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `CompactionTrigger object { type, agent }` - - `score_threshold: number` + Compacts the current context. Must be the final input item. - The score threshold for the file search. All values must be a floating point number between 0 and 1. + - `type: "compaction_trigger"` - - `ranker: optional "auto" or "default_2024_08_21"` + The type of the item. Always `compaction_trigger`. - The ranker to use for the file search. If not specified will use the `auto` ranker. + - `"compaction_trigger"` - - `"auto"` + - `agent: optional object { agent_name }` - - `"default_2024_08_21"` + The agent that produced this item. - - `FunctionTool object { function, type }` + - `agent_name: string` - - `function: FunctionDefinition` + The canonical name of the agent that produced this item. - - `name: string` + - `ItemReference object { id, agent, 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. + An internal identifier for an item to reference. - - `description: optional string` + - `id: string` - A description of what the function does, used by the model to choose when and how to call the function. + The ID of the item to reference. - - `parameters: optional FunctionParameters` + - `agent: optional object { agent_name }` - The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + The agent that produced this item. - Omitting `parameters` defines a function with an empty parameter list. + - `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 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](https://platform.openai.com/docs/guides/function-calling). + - `type: optional "item_reference"` - - `type: "function"` + The type of item to reference. Always `item_reference`. - The type of tool being defined: `function` + - `"item_reference"` - - `"function"` + - `Program object { id, call_id, code, 3 more }` - - `truncation_strategy: object { type, last_messages }` + - `id: 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 unique ID of this program item. - - `type: "auto" or "last_messages"` + - `call_id: string` - 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 stable call ID of the program item. - - `"auto"` + - `code: string` - - `"last_messages"` + The JavaScript source executed by programmatic tool calling. - - `last_messages: optional number` + - `fingerprint: string` - The number of most recent messages from the thread when constructing the context for the run. + Opaque program replay fingerprint that must be round-tripped. - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + - `type: "program"` - 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 item type. Always `program`. - - `completion_tokens: number` + - `"program"` - Number of completion tokens used over the course of the run. + - `agent: optional object { agent_name }` - - `prompt_tokens: number` + The agent that produced this item. - Number of prompt tokens used over the course of the run. + - `agent_name: string` - - `total_tokens: number` + The canonical name of the agent that produced this item. - Total number of tokens used (prompt + completion). + - `ProgramOutput object { id, call_id, result, 3 more }` - - `temperature: optional number` + - `id: string` - The sampling temperature used for this run. If not set, defaults to 1. + The unique ID of this program output item. - - `top_p: optional number` + - `call_id: string` - The nucleus sampling value used for this run. If not set, defaults to 1. + The call ID of the program item. - - `event: "thread.run.created"` + - `result: string` - - `"thread.run.created"` + The result produced by the program item. - - `ThreadRunQueued object { data, event }` + - `status: "completed" or "incomplete"` - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to a `queued` status. + The terminal status of the program output. - - `data: Run` + - `"completed"` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `"incomplete"` - - `event: "thread.run.queued"` + - `type: "program_output"` - - `"thread.run.queued"` + The item type. Always `program_output`. - - `ThreadRunInProgress object { data, event }` + - `"program_output"` - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to an `in_progress` status. + - `agent: optional object { agent_name }` - - `data: Run` + The agent that produced this item. - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `agent_name: string` - - `event: "thread.run.in_progress"` + The canonical name of the agent that produced this item. - - `"thread.run.in_progress"` +- `instructions: optional string` - - `ThreadRunRequiresAction object { data, event }` + A system (or developer) message inserted into the model's context. - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to a `requires_action` status. + 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. - - `data: Run` +- `max_output_tokens: optional number` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + 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). - - `event: "thread.run.requires_action"` +- `max_tool_calls: optional number` - - `"thread.run.requires_action"` + 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. - - `ThreadRunCompleted object { data, event }` +- `metadata: optional map[string]` - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) is completed. + 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. - - `data: Run` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). +- `model: optional "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` - - `event: "thread.run.completed"` + 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. - - `"thread.run.completed"` + - `"gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more` - - `ThreadRunIncomplete object { data, event }` + 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. - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) ends with status `incomplete`. + - `"gpt-5.6-sol"` - - `data: Run` + - `"gpt-5.6-terra"` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `"gpt-5.6-luna"` - - `event: "thread.run.incomplete"` + - `"gpt-5.4"` - - `"thread.run.incomplete"` + - `"gpt-5.4-mini"` - - `ThreadRunFailed object { data, event }` + - `"gpt-5.4-nano"` - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) fails. + - `"gpt-5.4-mini-2026-03-17"` - - `data: Run` + - `"gpt-5.4-nano-2026-03-17"` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `"gpt-5.3-chat-latest"` - - `event: "thread.run.failed"` + - `"gpt-5.2"` - - `"thread.run.failed"` + - `"gpt-5.2-2025-12-11"` - - `ThreadRunCancelling object { data, event }` + - `"gpt-5.2-chat-latest"` - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to a `cancelling` status. + - `"gpt-5.2-pro"` - - `data: Run` + - `"gpt-5.2-pro-2025-12-11"` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `"gpt-5.1"` - - `event: "thread.run.cancelling"` + - `"gpt-5.1-2025-11-13"` - - `"thread.run.cancelling"` + - `"gpt-5.1-codex"` - - `ThreadRunCancelled object { data, event }` + - `"gpt-5.1-mini"` - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) is cancelled. + - `"gpt-5.1-chat-latest"` - - `data: Run` + - `"gpt-5"` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `"gpt-5-mini"` - - `event: "thread.run.cancelled"` + - `"gpt-5-nano"` - - `"thread.run.cancelled"` + - `"gpt-5-2025-08-07"` - - `ThreadRunExpired object { data, event }` + - `"gpt-5-mini-2025-08-07"` - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) expires. + - `"gpt-5-nano-2025-08-07"` - - `data: Run` + - `"gpt-5-chat-latest"` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `"gpt-4.1"` - - `event: "thread.run.expired"` + - `"gpt-4.1-mini"` - - `"thread.run.expired"` + - `"gpt-4.1-nano"` - - `ThreadRunStepCreated object { data, event }` + - `"gpt-4.1-2025-04-14"` - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is created. + - `"gpt-4.1-mini-2025-04-14"` - - `data: RunStep` + - `"gpt-4.1-nano-2025-04-14"` - Represents a step in execution of a run. + - `"o4-mini"` - - `id: string` + - `"o4-mini-2025-04-16"` - The identifier of the run step, which can be referenced in API endpoints. + - `"o3"` - - `assistant_id: string` + - `"o3-2025-04-16"` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. + - `"o3-mini"` - - `cancelled_at: number` + - `"o3-mini-2025-01-31"` - The Unix timestamp (in seconds) for when the run step was cancelled. + - `"o1"` - - `completed_at: number` + - `"o1-2024-12-17"` - The Unix timestamp (in seconds) for when the run step completed. + - `"o1-preview"` - - `created_at: number` + - `"o1-preview-2024-09-12"` - The Unix timestamp (in seconds) for when the run step was created. + - `"o1-mini"` - - `expired_at: number` + - `"o1-mini-2024-09-12"` - The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. + - `"gpt-4o"` - - `failed_at: number` + - `"gpt-4o-2024-11-20"` - The Unix timestamp (in seconds) for when the run step failed. + - `"gpt-4o-2024-08-06"` - - `last_error: object { code, message }` + - `"gpt-4o-2024-05-13"` - The last error associated with this run step. Will be `null` if there are no errors. + - `"gpt-4o-audio-preview"` - - `code: "server_error" or "rate_limit_exceeded"` + - `"gpt-4o-audio-preview-2024-10-01"` - One of `server_error` or `rate_limit_exceeded`. + - `"gpt-4o-audio-preview-2024-12-17"` - - `"server_error"` + - `"gpt-4o-audio-preview-2025-06-03"` - - `"rate_limit_exceeded"` + - `"gpt-4o-mini-audio-preview"` - - `message: string` + - `"gpt-4o-mini-audio-preview-2024-12-17"` - A human-readable description of the error. + - `"gpt-4o-search-preview"` - - `metadata: Metadata` + - `"gpt-4o-mini-search-preview"` - 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. + - `"gpt-4o-search-preview-2025-03-11"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `"gpt-4o-mini-search-preview-2025-03-11"` - - `object: "thread.run.step"` + - `"chatgpt-4o-latest"` - The object type, which is always `thread.run.step`. + - `"codex-mini-latest"` - - `"thread.run.step"` + - `"gpt-4o-mini"` - - `run_id: string` + - `"gpt-4o-mini-2024-07-18"` - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. + - `"gpt-4-turbo"` - - `status: "in_progress" or "cancelled" or "failed" or 2 more` + - `"gpt-4-turbo-2024-04-09"` - The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. + - `"gpt-4-0125-preview"` - - `"in_progress"` + - `"gpt-4-turbo-preview"` - - `"cancelled"` + - `"gpt-4-1106-preview"` - - `"failed"` + - `"gpt-4-vision-preview"` - - `"completed"` + - `"gpt-4"` - - `"expired"` + - `"gpt-4-0314"` - - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` + - `"gpt-4-0613"` - The details of the run step. + - `"gpt-4-32k"` - - `MessageCreationStepDetails object { message_creation, type }` + - `"gpt-4-32k-0314"` - Details of the message creation by the run step. + - `"gpt-4-32k-0613"` - - `message_creation: object { message_id }` + - `"gpt-3.5-turbo"` - - `message_id: string` + - `"gpt-3.5-turbo-16k"` - The ID of the message that was created by this run step. + - `"gpt-3.5-turbo-0301"` - - `type: "message_creation"` + - `"gpt-3.5-turbo-0613"` - Always `message_creation`. + - `"gpt-3.5-turbo-1106"` - - `"message_creation"` + - `"gpt-3.5-turbo-0125"` - - `ToolCallsStepDetails object { tool_calls, type }` + - `"gpt-3.5-turbo-16k-0613"` - Details of the tool call. + - `"o1-pro"` - - `tool_calls: array of ToolCall` + - `"o1-pro-2025-03-19"` - 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`. + - `"o3-pro"` - - `CodeInterpreterToolCall object { id, code_interpreter, type }` + - `"o3-pro-2025-06-10"` - Details of the Code Interpreter tool call the run step was involved in. + - `"o3-deep-research"` - - `id: string` + - `"o3-deep-research-2025-06-26"` - The ID of the tool call. + - `"o4-mini-deep-research"` - - `code_interpreter: object { input, outputs }` + - `"o4-mini-deep-research-2025-06-26"` - The Code Interpreter tool call definition. + - `"computer-use-preview"` - - `input: string` + - `"computer-use-preview-2025-03-11"` - The input to the Code Interpreter tool call. + - `"gpt-5-codex"` - - `outputs: array of object { logs, type } or object { image, type }` + - `"gpt-5-pro"` - 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. + - `"gpt-5-pro-2025-10-06"` - - `Logs object { logs, type }` + - `"gpt-5.1-codex-max"` - Text output from the Code Interpreter tool call as part of a run step. + - `string` - - `logs: string` +- `moderation: optional object { model, policy }` - The text output from the Code Interpreter tool call. + Configuration for running moderation on the input and output of this response. - - `type: "logs"` + - `model: string` - Always `logs`. + The moderation model to use for moderated completions, e.g. 'omni-moderation-latest'. - - `"logs"` + - `policy: optional object { input, output }` - - `Image object { image, type }` + The policy to apply to moderated response input and output. - - `image: object { file_id }` + - `input: optional object { mode }` - - `file_id: string` + The moderation policy for the response input. - The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. + - `mode: "score" or "block"` - - `type: "image"` + - `"score"` - Always `image`. + - `"block"` - - `"image"` + - `output: optional object { mode }` - - `type: "code_interpreter"` + The moderation policy for the response output. - The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + - `mode: "score" or "block"` - - `"code_interpreter"` + - `"score"` - - `FileSearchToolCall object { id, file_search, type }` + - `"block"` - - `id: string` +- `multi_agent: optional object { enabled, max_concurrent_subagents }` - The ID of the tool call object. + Configuration for server-hosted multi-agent execution. - - `file_search: object { ranking_options, results }` + - `enabled: boolean` - For now, this is always going to be an empty object. + Whether to enable server-hosted multi-agent execution for this response. - - `ranking_options: optional object { ranker, score_threshold }` + - `max_concurrent_subagents: optional number` - The ranking options for the file search. + `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. - - `ranker: "auto" or "default_2024_08_21"` +- `parallel_tool_calls: optional boolean` - The ranker to use for the file search. If not specified will use the `auto` ranker. + Whether to allow the model to run tool calls in parallel. - - `"auto"` +- `previous_response_id: optional string` - - `"default_2024_08_21"` + 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`. - - `score_threshold: number` +- `prompt: optional BetaResponsePrompt` - The score threshold for the file search. All values must be a floating point number between 0 and 1. + Reference to a prompt template and its variables. + [Learn more](/docs/guides/text?api-mode=responses#reusable-prompts). - - `results: optional array of object { file_id, file_name, score, content }` + - `id: string` - The results of the file search. + The unique identifier of the prompt template to use. - - `file_id: string` + - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` - The ID of the file that result was found in. + 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_name: string` + - `string` - The name of the file that result was found in. + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `score: number` + A text input to the model. - The score of the result. All values must be a floating point number between 0 and 1. + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `content: optional array of object { text, type }` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - The content of the result that was found. The content is only included if requested via the include query parameter. + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `text: optional string` + A file input to the model. - The text content of the file. + - `version: optional string` - - `type: optional "text"` + Optional version of the prompt template. - The type of the content. +- `prompt_cache_key: optional string` - - `"text"` + 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: "file_search"` +- `prompt_cache_options: optional object { mode, ttl }` - The type of tool call. This is always going to be `file_search` for this type of tool 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. - - `"file_search"` + - `mode: optional "implicit" or "explicit"` - - `FunctionToolCall object { id, function, type }` + Controls whether OpenAI automatically creates an implicit cache breakpoint. Defaults to `implicit`. With `implicit`, OpenAI creates one implicit breakpoint and writes up to the latest three explicit breakpoints in the request. With `explicit`, OpenAI does not create an implicit breakpoint and writes up to the latest four explicit breakpoints. If there are no explicit breakpoints, the request does not use prompt caching. - - `id: string` + - `"implicit"` - The ID of the tool call object. + - `"explicit"` - - `function: object { arguments, name, output }` + - `ttl: optional "30m"` - The definition of the function that was called. + 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. - - `arguments: string` + - `"30m"` - The arguments passed to the function. +- `prompt_cache_retention: optional "in_memory" or "24h"` - - `name: string` + Deprecated. Use `prompt_cache_options.ttl` instead. - The name of the function. + 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. - - `output: string` + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - - `type: "function"` + - `"in_memory"` - The type of tool call. This is always going to be `function` for this type of tool call. + - `"24h"` - - `"function"` +- `reasoning: optional object { context, effort, generate_summary, 2 more }` - - `type: "tool_calls"` + **gpt-5 and o-series models only** - Always `tool_calls`. + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - `"tool_calls"` + - `context: optional "auto" or "current_turn" or "all_turns"` - - `thread_id: string` + Controls which reasoning items are rendered back to the model on later turns. + When returned on a response, this is the effective reasoning context mode + used for the response. - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. + - `"auto"` - - `type: "message_creation" or "tool_calls"` + - `"current_turn"` - The type of run step, which can be either `message_creation` or `tool_calls`. + - `"all_turns"` - - `"message_creation"` + - `effort: optional "none" or "minimal" or "low" or 4 more` - - `"tool_calls"` + 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. - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + - `"none"` - Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. + - `"minimal"` - - `completion_tokens: number` + - `"low"` - Number of completion tokens used over the course of the run step. + - `"medium"` - - `prompt_tokens: number` + - `"high"` - Number of prompt tokens used over the course of the run step. + - `"xhigh"` - - `total_tokens: number` + - `"max"` - Total number of tokens used (prompt + completion). + - `generate_summary: optional "auto" or "concise" or "detailed"` - - `event: "thread.run.step.created"` + **Deprecated:** use `summary` instead. - - `"thread.run.step.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`. - - `ThreadRunStepInProgress object { data, event }` + - `"auto"` - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) moves to an `in_progress` state. + - `"concise"` - - `data: RunStep` + - `"detailed"` - Represents a step in execution of a run. + - `mode: optional string or "standard" or "pro"` - - `event: "thread.run.step.in_progress"` + Controls the reasoning execution mode for the request. - - `"thread.run.step.in_progress"` + When returned on a response, this is the effective execution mode. - - `ThreadRunStepDelta object { data, event }` + - `string` - Occurs when parts of a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) are being streamed. + - `"standard" or "pro"` - - `data: RunStepDeltaEvent` + Controls the reasoning execution mode for the request. - Represents a run step delta i.e. any changed fields on a run step during streaming. + When returned on a response, this is the effective execution mode. - - `id: string` + - `"standard"` - The identifier of the run step, which can be referenced in API endpoints. + - `"pro"` - - `delta: RunStepDelta` + - `summary: optional "auto" or "concise" or "detailed"` - The delta containing the fields that have changed on the run step. + 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`. - - `step_details: optional RunStepDeltaMessageDelta or ToolCallDeltaObject` + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - The details of the run step. + - `"auto"` - - `RunStepDeltaMessageDelta object { type, message_creation }` + - `"concise"` - Details of the message creation by the run step. + - `"detailed"` - - `type: "message_creation"` +- `safety_identifier: optional string` - Always `message_creation`. + 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). - - `"message_creation"` +- `service_tier: optional "auto" or "default" or "flex" or 2 more` - - `message_creation: optional object { message_id }` + Specifies the processing type used for serving the request. - - `message_id: 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 ID of the message that was created by this run step. + 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. - - `ToolCallDeltaObject object { type, tool_calls }` + - `"auto"` - Details of the tool call. + - `"default"` - - `type: "tool_calls"` + - `"flex"` - Always `tool_calls`. + - `"scale"` - - `"tool_calls"` + - `"priority"` - - `tool_calls: optional array of ToolCallDelta` +- `store: optional boolean` - 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`. + Whether to store the generated model response for later retrieval via + API. - - `CodeInterpreterToolCallDelta object { index, type, id, code_interpreter }` +- `stream: optional boolean` - Details of the Code Interpreter tool call the run step was involved in. + 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. - - `index: number` +- `stream_options: optional object { include_obfuscation }` - The index of the tool call in the tool calls array. + Options for streaming responses. Only set this when you set `stream: true`. - - `type: "code_interpreter"` + - `include_obfuscation: optional boolean` - The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + 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. - - `"code_interpreter"` +- `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. + We generally recommend altering this or `top_p` but not both. - The ID of the tool call. +- `text: optional BetaResponseTextConfig` - - `code_interpreter: optional object { input, outputs }` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - The Code Interpreter tool call definition. + - [Text inputs and outputs](/docs/guides/text) + - [Structured Outputs](/docs/guides/structured-outputs) - - `input: optional string` + - `format: optional BetaResponseFormatTextConfig` - The input to the Code Interpreter tool call. + An object specifying the format that the model must output. - - `outputs: optional array of CodeInterpreterLogs or CodeInterpreterOutputImage` + 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 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 default format is `{ "type": "text" }` with no additional options. - - `CodeInterpreterLogs object { index, type, logs }` + **Not recommended for gpt-4o and newer models:** - Text output from the Code Interpreter tool call as part of a run step. + 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. - - `index: number` + - `Text object { type }` - The index of the output in the outputs array. + Default response format. Used to generate text responses. - - `type: "logs"` + - `type: "text"` - Always `logs`. + The type of response format being defined. Always `text`. - - `"logs"` + - `"text"` - - `logs: optional string` + - `BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` - The text output from the Code Interpreter tool call. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - - `CodeInterpreterOutputImage object { index, type, image }` + - `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 output in the outputs array. + - `schema: map[unknown]` - - `type: "image"` + 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`. + - `type: "json_schema"` - - `"image"` + The type of response format being defined. Always `json_schema`. - - `image: optional object { file_id }` + - `"json_schema"` - - `file_id: optional string` + - `description: optional string` - The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `FileSearchToolCallDelta object { file_search, index, type, id }` + - `strict: optional boolean` - - `file_search: unknown` + 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. + - `JSONObject object { type }` - - `index: number` + 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 index of the tool call in the tool calls array. + - `type: "json_object"` - - `type: "file_search"` + The type of response format being defined. Always `json_object`. - The type of tool call. This is always going to be `file_search` for this type of tool call. + - `"json_object"` - - `"file_search"` + - `verbosity: optional "low" or "medium" or "high"` - - `id: 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 ID of the tool call object. + - `"low"` - - `FunctionToolCallDelta object { index, type, id, function }` + - `"medium"` - - `index: number` + - `"high"` - The index of the tool call in the tool calls array. +- `tool_choice: optional BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` - - `type: "function"` + 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 tool call. This is always going to be `function` for this type of tool call. + - `BetaToolChoiceOptions = "none" or "auto" or "required"` - - `"function"` + Controls which (if any) tool is called by the model. - - `id: optional string` + `none` means the model will not call any tool and instead generates a message. - The ID of the tool call object. + `auto` means the model can pick between generating a message or calling one or + more tools. - - `function: optional object { arguments, name, output }` + `required` means the model must call one or more tools. - The definition of the function that was called. + - `"none"` - - `arguments: optional string` + - `"auto"` - The arguments passed to the function. + - `"required"` - - `name: optional string` + - `BetaToolChoiceAllowed object { mode, tools, type }` - The name of the function. + Constrains the tools available to the model to a pre-defined set. - - `output: optional string` + - `mode: "auto" or "required"` - The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. + Constrains the tools available to the model to a pre-defined set. - - `object: "thread.run.step.delta"` + `auto` allows the model to pick from among the allowed tools and generate a + message. - The object type, which is always `thread.run.step.delta`. + `required` requires the model to call one or more of the allowed tools. - - `"thread.run.step.delta"` + - `"auto"` - - `event: "thread.run.step.delta"` + - `"required"` - - `"thread.run.step.delta"` + - `tools: array of map[unknown]` - - `ThreadRunStepCompleted object { data, event }` + A list of tool definitions that the model should be allowed to call. - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is completed. + For the Responses API, the list of tool definitions might look like: - - `data: RunStep` + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - Represents a step in execution of a run. + - `type: "allowed_tools"` - - `event: "thread.run.step.completed"` + Allowed tool configuration type. Always `allowed_tools`. - - `"thread.run.step.completed"` + - `"allowed_tools"` - - `ThreadRunStepFailed object { data, event }` + - `BetaToolChoiceTypes object { type }` - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) fails. + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](/docs/guides/tools). - - `data: RunStep` + - `type: "file_search" or "web_search_preview" or "computer" or 5 more` - Represents a step in execution of a run. + The type of hosted tool the model should to use. Learn more about + [built-in tools](/docs/guides/tools). - - `event: "thread.run.step.failed"` + Allowed values are: - - `"thread.run.step.failed"` + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - - `ThreadRunStepCancelled object { data, event }` + - `"file_search"` - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is cancelled. + - `"web_search_preview"` - - `data: RunStep` + - `"computer"` - Represents a step in execution of a run. + - `"computer_use_preview"` - - `event: "thread.run.step.cancelled"` + - `"computer_use"` - - `"thread.run.step.cancelled"` + - `"web_search_preview_2025_03_11"` - - `ThreadRunStepExpired object { data, event }` + - `"image_generation"` - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) expires. + - `"code_interpreter"` - - `data: RunStep` + - `BetaToolChoiceFunction object { name, type }` - Represents a step in execution of a run. + Use this option to force the model to call a specific function. - - `event: "thread.run.step.expired"` + - `name: string` - - `"thread.run.step.expired"` + The name of the function to call. - - `ThreadMessageCreated object { data, event }` + - `type: "function"` - Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) is created. + For function calling, the type is always `function`. - - `data: Message` + - `"function"` - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + - `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 identifier, which can be referenced in API endpoints. + - `server_label: string` - - `assistant_id: string` + The label of the MCP server to use. - If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. + - `type: "mcp"` - - `attachments: array of object { file_id, tools }` + For MCP tools, the type is always `mcp`. - A list of files attached to the message, and the tools they were added to. + - `"mcp"` - - `file_id: optional string` + - `name: optional string` - The ID of the file to attach to the message. + The name of the tool to call on the server. - - `tools: optional array of CodeInterpreterTool or object { type }` + - `BetaToolChoiceCustom object { name, type }` - The tools to add this file to. + Use this option to force the model to call a specific custom tool. - - `CodeInterpreterTool object { type }` + - `name: string` - - `AssistantToolsFileSearchTypeOnly object { type }` + The name of the custom tool to call. - - `type: "file_search"` + - `type: "custom"` - The type of tool being defined: `file_search` + For custom tool calling, the type is always `custom`. - - `"file_search"` + - `"custom"` - - `completed_at: number` + - `BetaSpecificProgrammaticToolCallingParam object { type }` - The Unix timestamp (in seconds) for when the message was completed. + - `type: "programmatic_tool_calling"` - - `content: array of MessageContent` + The tool to call. Always `programmatic_tool_calling`. - The content of the message in array of text and/or images. + - `"programmatic_tool_calling"` - - `ImageFileContentBlock object { image_file, type }` + - `BetaToolChoiceApplyPatch object { type }` - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + Forces the model to call the apply_patch tool when executing a tool call. - - `image_file: ImageFile` + - `type: "apply_patch"` - - `file_id: string` + The tool to call. Always `apply_patch`. - The [File](https://platform.openai.com/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. + - `"apply_patch"` - - `detail: optional "auto" or "low" or "high"` + - `BetaToolChoiceShell 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`. + Forces the model to call the shell tool when a tool call is required. - - `"auto"` + - `type: "shell"` - - `"low"` + The tool to call. Always `shell`. - - `"high"` + - `"shell"` - - `type: "image_file"` +- `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` - Always `image_file`. + 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. - - `"image_file"` + We support the following categories of tools: - - `ImageURLContentBlock object { image_url, type }` + - **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. - References an image URL in the content of a message. + - `Function object { name, parameters, strict, 5 more }` - - `image_url: ImageURL` + 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). - - `url: string` + - `name: string` - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + The name of the function to call. - - `detail: optional "auto" or "low" or "high"` + - `parameters: 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` + A JSON schema object describing the parameters of the function. - - `"auto"` + - `strict: boolean` - - `"low"` + Whether strict parameter validation is enforced for this function tool. - - `"high"` + - `type: "function"` - - `type: "image_url"` + The type of the function tool. Always `function`. - The type of the content part. + - `"function"` - - `"image_url"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `TextContentBlock object { text, type }` + The tool invocation context(s). - The text content that is part of a message. + - `"direct"` - - `text: Text` + - `"programmatic"` - - `annotations: array of Annotation` + - `defer_loading: optional boolean` - - `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` + Whether this function is deferred and loaded via tool 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. + - `description: optional string` - - `end_index: number` + A description of the function. Used by the model to determine whether or not to call the function. - - `file_citation: object { file_id }` + - `output_schema: optional map[unknown]` - - `file_id: string` + A JSON schema object describing the JSON value encoded in string outputs for this function. - The ID of the specific File the citation is from. + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - - `start_index: 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). - - `text: string` + - `type: "file_search"` - The text in the message content that needs to be replaced. + The type of the file search tool. Always `file_search`. - - `type: "file_citation"` + - `"file_search"` - Always `file_citation`. + - `vector_store_ids: array of string` - - `"file_citation"` + The IDs of the vector stores to search. - - `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` + - `filters: optional object { key, type, value } or object { filters, type }` - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + A filter to apply. - - `end_index: number` + - `ComparisonFilter object { key, type, value }` - - `file_path: object { file_id }` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `file_id: string` + - `key: string` - The ID of the file that was generated. + The key to compare against the value. - - `start_index: number` + - `type: "eq" or "ne" or "gt" or 5 more` - - `text: string` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The text in the message content that needs to be replaced. + - `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: "file_path"` + - `"eq"` - Always `file_path`. + - `"ne"` - - `"file_path"` + - `"gt"` - - `value: string` + - `"gte"` - The data that makes up the text. + - `"lt"` - - `type: "text"` + - `"lte"` - Always `text`. + - `"in"` - - `"text"` + - `"nin"` - - `RefusalContentBlock object { refusal, type }` + - `value: string or number or boolean or array of string or number` - The refusal content generated by the assistant. + The value to compare against the attribute key; supports string, number, or boolean types. - - `refusal: string` + - `string` - - `type: "refusal"` + - `number` - Always `refusal`. + - `boolean` - - `"refusal"` + - `array of string or number` - - `created_at: number` + - `string` - The Unix timestamp (in seconds) for when the message was created. + - `number` - - `incomplete_at: number` + - `CompoundFilter object { filters, type }` - The Unix timestamp (in seconds) for when the message was marked as incomplete. + Combine multiple filters using `and` or `or`. - - `incomplete_details: object { reason }` + - `filters: array of object { key, type, value } or unknown` - On an incomplete message, details about why the message is incomplete. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` + - `ComparisonFilter object { key, type, value }` - The reason the message is incomplete. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `"content_filter"` + - `key: string` - - `"max_tokens"` + The key to compare against the value. - - `"run_cancelled"` + - `type: "eq" or "ne" or "gt" or 5 more` - - `"run_expired"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `"run_failed"` + - `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 - - `metadata: Metadata` + - `"eq"` - 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. + - `"ne"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `"gt"` - - `object: "thread.message"` + - `"gte"` - The object type, which is always `thread.message`. + - `"lt"` - - `"thread.message"` + - `"lte"` - - `role: "user" or "assistant"` + - `"in"` - The entity that produced the message. One of `user` or `assistant`. + - `"nin"` - - `"user"` + - `value: string or number or boolean or array of string or number` - - `"assistant"` + The value to compare against the attribute key; supports string, number, or boolean types. - - `run_id: string` + - `string` - The ID of the [run](https://platform.openai.com/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` - - `status: "in_progress" or "incomplete" or "completed"` + - `boolean` - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + - `array of string or number` - - `"in_progress"` + - `string` - - `"incomplete"` + - `number` - - `"completed"` + - `unknown` - - `thread_id: string` + - `type: "and" or "or"` - The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + Type of operation: `and` or `or`. - - `event: "thread.message.created"` + - `"and"` - - `"thread.message.created"` + - `"or"` - - `ThreadMessageInProgress object { data, event }` + - `max_num_results: optional number` - Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) moves to an `in_progress` state. + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `data: Message` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + Ranking options for search. - - `event: "thread.message.in_progress"` + - `hybrid_search: optional object { embedding_weight, text_weight }` - - `"thread.message.in_progress"` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `ThreadMessageDelta object { data, event }` + - `embedding_weight: number` - Occurs when parts of a [Message](https://platform.openai.com/docs/api-reference/messages/object) are being streamed. + The weight of the embedding in the reciprocal ranking fusion. - - `data: MessageDeltaEvent` + - `text_weight: number` - Represents a message delta i.e. any changed fields on a message during streaming. + The weight of the text in the reciprocal ranking fusion. - - `id: string` + - `ranker: optional "auto" or "default-2024-11-15"` - The identifier of the message, which can be referenced in API endpoints. + The ranker to use for the file search. - - `delta: MessageDelta` + - `"auto"` - The delta containing the fields that have changed on the Message. + - `"default-2024-11-15"` - - `content: optional array of MessageContentDelta` + - `score_threshold: optional number` - The content of the message in array of text and/or images. + 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. - - `ImageFileDeltaBlock object { index, type, image_file }` + - `Computer object { type }` - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `index: number` + - `type: "computer"` - The index of the content part in the message. + The type of the computer tool. Always `computer`. - - `type: "image_file"` + - `"computer"` - Always `image_file`. + - `ComputerUsePreview object { display_height, display_width, environment, type }` - - `"image_file"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `image_file: optional ImageFileDelta` + - `display_height: number` - - `detail: optional "auto" or "low" or "high"` + The height of the computer display. - 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`. + - `display_width: number` - - `"auto"` + The width of the computer display. - - `"low"` + - `environment: "windows" or "mac" or "linux" or 2 more` - - `"high"` + The type of computer environment to control. - - `file_id: optional string` + - `"windows"` - The [File](https://platform.openai.com/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. + - `"mac"` - - `TextDeltaBlock object { index, type, text }` + - `"linux"` - The text content that is part of a message. + - `"ubuntu"` - - `index: number` + - `"browser"` - The index of the content part in the message. + - `type: "computer_use_preview"` - - `type: "text"` + The type of the computer use tool. Always `computer_use_preview`. - Always `text`. + - `"computer_use_preview"` - - `"text"` + - `WebSearch object { type, filters, search_context_size, user_location }` - - `text: optional TextDelta` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - - `annotations: optional array of AnnotationDelta` + - `type: "web_search" or "web_search_2025_08_26"` - - `FileCitationDeltaAnnotation object { index, type, end_index, 3 more }` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - 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. + - `"web_search"` - - `index: number` + - `"web_search_2025_08_26"` - The index of the annotation in the text content part. + - `filters: optional object { allowed_domains }` - - `type: "file_citation"` + Filters for the search. - Always `file_citation`. + - `allowed_domains: optional array of string` - - `"file_citation"` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `end_index: optional number` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `file_citation: optional object { file_id, quote }` + - `search_context_size: optional "low" or "medium" or "high"` - - `file_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 specific File the citation is from. + - `"low"` - - `quote: optional string` + - `"medium"` - The specific quote in the file. + - `"high"` - - `start_index: optional number` + - `user_location: optional object { city, country, region, 2 more }` - - `text: optional string` + The approximate location of the user. - The text in the message content that needs to be replaced. + - `city: optional string` - - `FilePathDeltaAnnotation object { index, type, end_index, 3 more }` + Free text input for the city of the user, e.g. `San Francisco`. - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + - `country: optional string` - - `index: number` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The index of the annotation in the text content part. + - `region: optional string` - - `type: "file_path"` + Free text input for the region of the user, e.g. `California`. - Always `file_path`. + - `timezone: optional string` - - `"file_path"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `end_index: optional number` + - `type: optional "approximate"` - - `file_path: optional object { file_id }` + The type of location approximation. Always `approximate`. - - `file_id: optional string` + - `"approximate"` - The ID of the file that was generated. + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `start_index: 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). - - `text: optional string` + - `server_label: string` - The text in the message content that needs to be replaced. + A label for this MCP server, used to identify it in tool calls. - - `value: optional string` + - `type: "mcp"` - The data that makes up the text. + The type of the MCP tool. Always `mcp`. - - `RefusalDeltaBlock object { index, type, refusal }` + - `"mcp"` - The refusal content that is part of a message. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `index: number` + The tool invocation context(s). - The index of the refusal part in the message. + - `"direct"` - - `type: "refusal"` + - `"programmatic"` - Always `refusal`. + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `"refusal"` + List of allowed tool names or a filter object. - - `refusal: optional string` + - `McpAllowedTools = array of string` - - `ImageURLDeltaBlock object { index, type, image_url }` + A string array of allowed tool names - References an image URL in the content of a message. + - `McpToolFilter object { read_only, tool_names }` - - `index: number` + A filter object to specify which tools are allowed. - The index of the content part in the message. + - `read_only: optional boolean` - - `type: "image_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. - Always `image_url`. + - `tool_names: optional array of string` - - `"image_url"` + List of allowed tool names. - - `image_url: optional ImageURLDelta` + - `authorization: optional string` - - `detail: optional "auto" or "low" or "high"` + 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 detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `"auto"` + 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). - - `"low"` + Currently supported `connector_id` values are: - - `"high"` + - 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` - - `url: optional string` + - `"connector_dropbox"` - The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `"connector_gmail"` - - `role: optional "user" or "assistant"` + - `"connector_googlecalendar"` - The entity that produced the message. One of `user` or `assistant`. + - `"connector_googledrive"` - - `"user"` + - `"connector_microsoftteams"` - - `"assistant"` + - `"connector_outlookcalendar"` - - `object: "thread.message.delta"` + - `"connector_outlookemail"` - The object type, which is always `thread.message.delta`. + - `"connector_sharepoint"` - - `"thread.message.delta"` + - `defer_loading: optional boolean` - - `event: "thread.message.delta"` + Whether this MCP tool is deferred and discovered via tool search. - - `"thread.message.delta"` + - `headers: optional map[string]` - - `ThreadMessageCompleted object { data, event }` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) is completed. + - `require_approval: optional object { always, never } or "always" or "never"` - - `data: Message` + Specify which of the MCP server's tools require approval. - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + - `McpToolApprovalFilter object { always, never }` - - `event: "thread.message.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. - - `"thread.message.completed"` + - `always: optional object { read_only, tool_names }` - - `ThreadMessageIncomplete object { data, event }` + A filter object to specify which tools are allowed. - Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) ends before it is completed. + - `read_only: optional boolean` - - `data: 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. - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + - `tool_names: optional array of string` - - `event: "thread.message.incomplete"` + List of allowed tool names. - - `"thread.message.incomplete"` + - `never: optional object { read_only, tool_names }` - - `ErrorEvent object { data, event }` + A filter object to specify which tools are allowed. - Occurs when an [error](https://platform.openai.com/docs/guides/error-codes#api-errors) occurs. This can happen due to an internal server error or a timeout. + - `read_only: optional boolean` - - `data: ErrorObject` + 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` - - `message: string` + List of allowed tool names. - - `param: string` + - `McpToolApprovalSetting = "always" or "never"` - - `type: 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. - - `event: "error"` + - `"always"` - - `"error"` + - `"never"` -### Assistant Tool + - `server_description: optional string` -- `AssistantTool = CodeInterpreterTool or FileSearchTool or FunctionTool` + Optional description of the MCP server, used to provide more context. - - `CodeInterpreterTool object { type }` + - `server_url: optional string` - - `type: "code_interpreter"` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - The type of tool being defined: `code_interpreter` + - `tunnel_id: optional string` - - `"code_interpreter"` + 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. - - `FileSearchTool object { type, file_search }` + - `CodeInterpreter object { container, type, allowed_callers }` - - `type: "file_search"` + A tool that runs Python code to help generate a response to a prompt. - The type of tool being defined: `file_search` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `"file_search"` + 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_search: optional object { max_num_results, ranking_options }` + - `string` - Overrides for the file search tool. + The container ID. - - `max_num_results: optional number` + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - 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. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `type: "auto"` - - `ranking_options: optional object { score_threshold, ranker }` + Always `auto`. - 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. + - `"auto"` - See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `file_ids: optional array of string` - - `score_threshold: number` + An optional list of uploaded files to make available to your code. - The score threshold for the file search. All values must be a floating point number between 0 and 1. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `ranker: optional "auto" or "default_2024_08_21"` + The memory limit for the code interpreter container. - The ranker to use for the file search. If not specified will use the `auto` ranker. + - `"1g"` - - `"auto"` + - `"4g"` - - `"default_2024_08_21"` + - `"16g"` - - `FunctionTool object { function, type }` + - `"64g"` - - `function: FunctionDefinition` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `name: string` + Network access policy for the container. - 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. + - `BetaContainerNetworkPolicyDisabled object { type }` - - `description: optional string` + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - A description of what the function does, used by the model to choose when and how to call the function. + - `type: "code_interpreter"` - - `parameters: optional FunctionParameters` + The type of the code interpreter tool. Always `code_interpreter`. - The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + - `"code_interpreter"` - Omitting `parameters` defines a function with an empty parameter list. + - `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 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](https://platform.openai.com/docs/guides/function-calling). + - `"direct"` - - `type: "function"` + - `"programmatic"` - The type of tool being defined: `function` + - `ProgrammaticToolCalling object { type }` - - `"function"` + - `type: "programmatic_tool_calling"` -### Code Interpreter Tool + The type of the tool. Always `programmatic_tool_calling`. -- `CodeInterpreterTool object { type }` + - `"programmatic_tool_calling"` - - `type: "code_interpreter"` + - `ImageGeneration object { type, action, background, 9 more }` - The type of tool being defined: `code_interpreter` + A tool that generates images using the GPT image models. - - `"code_interpreter"` + - `type: "image_generation"` -### File Search Tool + The type of the image generation tool. Always `image_generation`. -- `FileSearchTool object { type, file_search }` + - `"image_generation"` - - `type: "file_search"` + - `action: optional "generate" or "edit" or "auto"` - The type of tool being defined: `file_search` + Whether to generate a new image or edit an existing image. Default: `auto`. - - `"file_search"` + - `"generate"` - - `file_search: optional object { max_num_results, ranking_options }` + - `"edit"` - Overrides for the file search tool. + - `"auto"` - - `max_num_results: optional number` + - `background: optional "transparent" or "opaque" or "auto"` - 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. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `"transparent"` - - `ranking_options: optional object { score_threshold, ranker }` + - `"opaque"` - 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. + - `"auto"` - See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `input_fidelity: optional "high" or "low"` - - `score_threshold: number` + 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 score threshold for the file search. All values must be a floating point number between 0 and 1. + - `"high"` - - `ranker: optional "auto" or "default_2024_08_21"` + - `"low"` - The ranker to use for the file search. If not specified will use the `auto` ranker. + - `input_image_mask: optional object { file_id, image_url }` - - `"auto"` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `"default_2024_08_21"` + - `file_id: optional string` -### Function Tool + File ID for the mask image. -- `FunctionTool object { function, type }` + - `image_url: optional string` - - `function: FunctionDefinition` + Base64-encoded mask image. - - `name: string` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - 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 image generation model to use. Default: `gpt-image-1`. - - `description: optional string` + - `string` - A description of what the function does, used by the model to choose when and how to call the function. + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `parameters: optional FunctionParameters` + The image generation model to use. Default: `gpt-image-1`. - The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + - `"gpt-image-1"` - Omitting `parameters` defines a function with an empty parameter list. + - `"gpt-image-1-mini"` - - `strict: optional boolean` + - `"gpt-image-1.5"` - 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](https://platform.openai.com/docs/guides/function-calling). + - `moderation: optional "auto" or "low"` - - `type: "function"` + Moderation level for the generated image. Default: `auto`. - The type of tool being defined: `function` + - `"auto"` - - `"function"` + - `"low"` -### Message Stream Event + - `output_compression: optional number` -- `MessageStreamEvent = object { data, event } or object { data, event } or object { data, event } or 2 more` + Compression level for the output image. Default: 100. - Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) is created. + - `output_format: optional "png" or "webp" or "jpeg"` - - `ThreadMessageCreated object { data, event }` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) is created. + - `"png"` - - `data: Message` + - `"webp"` - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + - `"jpeg"` - - `id: string` + - `partial_images: optional number` - The identifier, which can be referenced in API endpoints. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `assistant_id: string` + - `quality: optional "low" or "medium" or "high" or "auto"` - If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `attachments: array of object { file_id, tools }` + - `"low"` - A list of files attached to the message, and the tools they were added to. + - `"medium"` - - `file_id: optional string` + - `"high"` - The ID of the file to attach to the message. + - `"auto"` - - `tools: optional array of CodeInterpreterTool or object { type }` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - The tools to add this file to. + 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`. - - `CodeInterpreterTool object { type }` + - `string` - - `type: "code_interpreter"` + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - The type of tool being defined: `code_interpreter` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `"code_interpreter"` + - `"1024x1024"` - - `AssistantToolsFileSearchTypeOnly object { type }` + - `"1024x1536"` - - `type: "file_search"` + - `"1536x1024"` - The type of tool being defined: `file_search` + - `"auto"` - - `"file_search"` + - `LocalShell object { type }` - - `completed_at: number` + A tool that allows the model to execute shell commands in a local environment. - The Unix timestamp (in seconds) for when the message was completed. + - `type: "local_shell"` - - `content: array of MessageContent` + The type of the local shell tool. Always `local_shell`. - The content of the message in array of text and/or images. + - `"local_shell"` - - `ImageFileContentBlock object { image_file, type }` + - `Shell object { type, allowed_callers, environment }` - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + A tool that allows the model to execute shell commands. - - `image_file: ImageFile` + - `type: "shell"` - - `file_id: string` + The type of the shell tool. Always `shell`. - The [File](https://platform.openai.com/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. + - `"shell"` - - `detail: optional "auto" or "low" or "high"` + - `allowed_callers: optional array of "direct" or "programmatic"` - 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 tool invocation context(s). - - `"auto"` + - `"direct"` - - `"low"` + - `"programmatic"` - - `"high"` + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - `type: "image_file"` + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - Always `image_file`. + - `BetaLocalEnvironment object { type, skills }` - - `"image_file"` + - `BetaContainerReference object { container_id, type }` - - `ImageURLContentBlock object { image_url, type }` + - `Custom object { name, type, allowed_callers, 3 more }` - References an image URL in the content of a message. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `image_url: ImageURL` + - `name: string` - - `url: string` + The name of the custom tool, used to identify it in tool calls. - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `type: "custom"` - - `detail: optional "auto" or "low" or "high"` + The type of the custom tool. Always `custom`. - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + - `"custom"` - - `"auto"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"low"` + The tool invocation context(s). - - `"high"` + - `"direct"` - - `type: "image_url"` + - `"programmatic"` - The type of the content part. + - `defer_loading: optional boolean` - - `"image_url"` + Whether this tool should be deferred and discovered via tool search. - - `TextContentBlock object { text, type }` + - `description: optional string` - The text content that is part of a message. + Optional description of the custom tool, used to provide more context. - - `text: Text` + - `format: optional object { type } or object { definition, syntax, type }` - - `annotations: array of Annotation` + The input format for the custom tool. Default is unconstrained text. - - `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` + - `Text object { 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. + Unconstrained free-form text. - - `end_index: number` + - `type: "text"` - - `file_citation: object { file_id }` + Unconstrained text format. Always `text`. - - `file_id: string` + - `"text"` - The ID of the specific File the citation is from. + - `Grammar object { definition, syntax, type }` - - `start_index: number` + A grammar defined by the user. - - `text: string` + - `definition: string` - The text in the message content that needs to be replaced. + The grammar definition. - - `type: "file_citation"` + - `syntax: "lark" or "regex"` - Always `file_citation`. + The syntax of the grammar definition. One of `lark` or `regex`. - - `"file_citation"` + - `"lark"` - - `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` + - `"regex"` - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + - `type: "grammar"` - - `end_index: number` + Grammar format. Always `grammar`. - - `file_path: object { file_id }` + - `"grammar"` - - `file_id: string` + - `Namespace object { description, name, tools, type }` - The ID of the file that was generated. + Groups function/custom tools under a shared namespace. - - `start_index: number` + - `description: string` - - `text: string` + A description of the namespace shown to the model. - The text in the message content that needs to be replaced. + - `name: string` - - `type: "file_path"` + The namespace name used in tool calls (for example, `crm`). - Always `file_path`. + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - - `"file_path"` + The function/custom tools available inside this namespace. - - `value: string` + - `Function object { name, type, allowed_callers, 5 more }` - The data that makes up the text. + - `name: string` - - `type: "text"` + - `type: "function"` - Always `text`. + - `"function"` - - `"text"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `RefusalContentBlock object { refusal, type }` + The tool invocation context(s). - The refusal content generated by the assistant. + - `"direct"` - - `refusal: string` + - `"programmatic"` - - `type: "refusal"` + - `defer_loading: optional boolean` - Always `refusal`. + Whether this function should be deferred and discovered via tool search. - - `"refusal"` + - `description: optional string` - - `created_at: number` + - `output_schema: optional map[unknown]` - The Unix timestamp (in seconds) for when the message was created. + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `incomplete_at: number` + - `parameters: optional unknown` - The Unix timestamp (in seconds) for when the message was marked as incomplete. + - `strict: optional boolean` - - `incomplete_details: object { reason }` + 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. - On an incomplete message, details about why the message is incomplete. + - `Custom object { name, type, allowed_callers, 3 more }` - - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - The reason the message is incomplete. + - `name: string` - - `"content_filter"` + The name of the custom tool, used to identify it in tool calls. - - `"max_tokens"` + - `type: "custom"` - - `"run_cancelled"` + The type of the custom tool. Always `custom`. - - `"run_expired"` + - `"custom"` - - `"run_failed"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `metadata: Metadata` + The tool invocation context(s). - 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. + - `"direct"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `"programmatic"` - - `object: "thread.message"` + - `defer_loading: optional boolean` - The object type, which is always `thread.message`. + Whether this tool should be deferred and discovered via tool search. - - `"thread.message"` + - `description: optional string` - - `role: "user" or "assistant"` + Optional description of the custom tool, used to provide more context. - The entity that produced the message. One of `user` or `assistant`. + - `format: optional object { type } or object { definition, syntax, type }` - - `"user"` + The input format for the custom tool. Default is unconstrained text. - - `"assistant"` + - `Text object { type }` - - `run_id: string` + Unconstrained free-form text. - The ID of the [run](https://platform.openai.com/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: "text"` - - `status: "in_progress" or "incomplete" or "completed"` + Unconstrained text format. Always `text`. - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + - `"text"` - - `"in_progress"` + - `Grammar object { definition, syntax, type }` - - `"incomplete"` + A grammar defined by the user. - - `"completed"` + - `definition: string` - - `thread_id: string` + The grammar definition. - The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + - `syntax: "lark" or "regex"` - - `event: "thread.message.created"` + The syntax of the grammar definition. One of `lark` or `regex`. - - `"thread.message.created"` + - `"lark"` - - `ThreadMessageInProgress object { data, event }` + - `"regex"` - Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) moves to an `in_progress` state. + - `type: "grammar"` - - `data: Message` + Grammar format. Always `grammar`. - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + - `"grammar"` - - `event: "thread.message.in_progress"` + - `type: "namespace"` - - `"thread.message.in_progress"` + The type of the tool. Always `namespace`. - - `ThreadMessageDelta object { data, event }` + - `"namespace"` - Occurs when parts of a [Message](https://platform.openai.com/docs/api-reference/messages/object) are being streamed. + - `ToolSearch object { type, description, execution, parameters }` - - `data: MessageDeltaEvent` + Hosted or BYOT tool search configuration for deferred tools. - Represents a message delta i.e. any changed fields on a message during streaming. + - `type: "tool_search"` - - `id: string` + The type of the tool. Always `tool_search`. - The identifier of the message, which can be referenced in API endpoints. + - `"tool_search"` - - `delta: MessageDelta` + - `description: optional string` - The delta containing the fields that have changed on the Message. + Description shown to the model for a client-executed tool search tool. - - `content: optional array of MessageContentDelta` + - `execution: optional "server" or "client"` - The content of the message in array of text and/or images. + Whether tool search is executed by the server or by the client. - - `ImageFileDeltaBlock object { index, type, image_file }` + - `"server"` - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + - `"client"` - - `index: number` + - `parameters: optional unknown` - The index of the content part in the message. + Parameter schema for a client-executed tool search tool. - - `type: "image_file"` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - Always `image_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). - - `"image_file"` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `image_file: optional ImageFileDelta` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `detail: optional "auto" or "low" or "high"` + - `"web_search_preview"` - 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`. + - `"web_search_preview_2025_03_11"` - - `"auto"` + - `search_content_types: optional array of "text" or "image"` - - `"low"` + - `"text"` - - `"high"` + - `"image"` - - `file_id: optional string` + - `search_context_size: optional "low" or "medium" or "high"` - The [File](https://platform.openai.com/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. + 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. - - `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. + - `user_location: optional object { type, city, country, 2 more }` - - `type: "text"` + The user's location. - Always `text`. + - `type: "approximate"` - - `"text"` + The type of location approximation. Always `approximate`. - - `text: optional TextDelta` + - `"approximate"` - - `annotations: optional array of AnnotationDelta` + - `city: optional string` - - `FileCitationDeltaAnnotation object { index, type, end_index, 3 more }` + Free text input for the city of the user, e.g. `San Francisco`. - 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. + - `country: optional string` - - `index: number` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The index of the annotation in the text content part. + - `region: optional string` - - `type: "file_citation"` + Free text input for the region of the user, e.g. `California`. - Always `file_citation`. + - `timezone: optional string` - - `"file_citation"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `end_index: optional number` + - `ApplyPatch object { type, allowed_callers }` - - `file_citation: optional object { file_id, quote }` + Allows the assistant to create, delete, or update files using unified diffs. - - `file_id: optional string` + - `type: "apply_patch"` - The ID of the specific File the citation is from. + The type of the tool. Always `apply_patch`. - - `quote: optional string` + - `"apply_patch"` - The specific quote in the file. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `start_index: optional number` + The tool invocation context(s). - - `text: optional string` + - `"direct"` - The text in the message content that needs to be replaced. + - `"programmatic"` - - `FilePathDeltaAnnotation object { index, type, end_index, 3 more }` +- `top_logprobs: optional number` - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + 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. - - `index: number` +- `top_p: optional number` - The index of the annotation in the text content part. + 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: "file_path"` + We generally recommend altering this or `temperature` but not both. - Always `file_path`. +- `truncation: optional "auto" or "disabled"` - - `"file_path"` + The truncation strategy to use for the model response. - - `end_index: optional number` + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. - - `file_path: optional object { file_id }` + - `"auto"` - - `file_id: optional string` + - `"disabled"` - The ID of the file that was generated. +- `user: optional string` - - `start_index: optional number` + 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). - - `text: optional string` +### Returns - The text in the message content that needs to be replaced. +- `BetaResponse object { id, created_at, error, 32 more }` - - `value: optional string` + - `id: string` - The data that makes up the text. + Unique identifier for this Response. - - `RefusalDeltaBlock object { index, type, refusal }` + - `created_at: number` - The refusal content that is part of a message. + Unix timestamp (in seconds) of when this Response was created. - - `index: number` + - `error: BetaResponseError` - The index of the refusal part in the message. + An error object returned when the model fails to generate a Response. - - `type: "refusal"` + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 16 more` - Always `refusal`. + The error code for the response. - - `"refusal"` + - `"server_error"` - - `refusal: optional string` + - `"rate_limit_exceeded"` - - `ImageURLDeltaBlock object { index, type, image_url }` + - `"invalid_prompt"` - References an image URL in the content of a message. + - `"bio_policy"` - - `index: number` + - `"vector_store_timeout"` - The index of the content part in the message. + - `"invalid_image"` - - `type: "image_url"` + - `"invalid_image_format"` - Always `image_url`. + - `"invalid_base64_image"` - - `"image_url"` + - `"invalid_image_url"` - - `image_url: optional ImageURLDelta` + - `"image_too_large"` - - `detail: optional "auto" or "low" or "high"` + - `"image_too_small"` - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. + - `"image_parse_error"` - - `"auto"` + - `"image_content_policy_violation"` - - `"low"` + - `"invalid_image_mode"` - - `"high"` + - `"image_file_too_large"` - - `url: optional string` + - `"unsupported_image_media_type"` - The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `"empty_image_file"` - - `role: optional "user" or "assistant"` + - `"failed_to_download_image"` - The entity that produced the message. One of `user` or `assistant`. + - `"image_file_not_found"` - - `"user"` + - `message: string` - - `"assistant"` + A human-readable description of the error. - - `object: "thread.message.delta"` + - `incomplete_details: object { reason }` - The object type, which is always `thread.message.delta`. + Details about why the response is incomplete. - - `"thread.message.delta"` + - `reason: optional "max_output_tokens" or "content_filter"` - - `event: "thread.message.delta"` + The reason why the response is incomplete. - - `"thread.message.delta"` + - `"max_output_tokens"` - - `ThreadMessageCompleted object { data, event }` + - `"content_filter"` - Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) is completed. + - `instructions: string or array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` - - `data: Message` + A system (or developer) message inserted into the model's context. - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + 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. - - `event: "thread.message.completed"` + - `string` - - `"thread.message.completed"` + A text input to the model, equivalent to a text input with the + `developer` role. - - `ThreadMessageIncomplete object { data, event }` + - `InputItemList = array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` - Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) ends before it is completed. + A list of one or many input items to the model, containing + different content types. - - `data: Message` + - `BetaEasyInputMessage object { content, role, phase, type }` - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + 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. - - `event: "thread.message.incomplete"` + - `content: string or BetaResponseInputMessageContentList` - - `"thread.message.incomplete"` + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. -### Run Step Stream Event + - `TextInput = string` -- `RunStepStreamEvent = object { data, event } or object { data, event } or object { data, event } or 4 more` + A text input to the model. - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is created. + - `BetaResponseInputMessageContentList = array of BetaResponseInputContent` - - `ThreadRunStepCreated object { data, event }` + A list of one or many input items to the model, containing different content + types. - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is created. + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `data: RunStep` + A text input to the model. - Represents a step in execution of a run. + - `text: string` - - `id: string` + The text input to the model. - The identifier of the run step, which can be referenced in API endpoints. + - `type: "input_text"` - - `assistant_id: string` + The type of the input item. Always `input_text`. - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. + - `"input_text"` - - `cancelled_at: number` + - `prompt_cache_breakpoint: optional object { mode }` - The Unix timestamp (in seconds) for when the run step was cancelled. + Marks the exact end of a reusable 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_at: number` + - `mode: "explicit"` - The Unix timestamp (in seconds) for when the run step completed. + The breakpoint mode. Always `explicit`. - - `created_at: number` + - `"explicit"` - The Unix timestamp (in seconds) for when the run step was created. + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `expired_at: number` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. + - `detail: "low" or "high" or "auto" or "original"` - - `failed_at: number` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The Unix timestamp (in seconds) for when the run step failed. + - `"low"` - - `last_error: object { code, message }` + - `"high"` - The last error associated with this run step. Will be `null` if there are no errors. + - `"auto"` - - `code: "server_error" or "rate_limit_exceeded"` + - `"original"` - One of `server_error` or `rate_limit_exceeded`. + - `type: "input_image"` - - `"server_error"` + The type of the input item. Always `input_image`. - - `"rate_limit_exceeded"` + - `"input_image"` - - `message: string` + - `file_id: optional string` - A human-readable description of the error. + The ID of the file to be sent to the model. - - `metadata: Metadata` + - `image_url: 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. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `prompt_cache_breakpoint: optional object { mode }` - - `object: "thread.run.step"` + Marks the exact end of a reusable 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 object type, which is always `thread.run.step`. + - `mode: "explicit"` - - `"thread.run.step"` + The breakpoint mode. Always `explicit`. - - `run_id: string` + - `"explicit"` - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `status: "in_progress" or "cancelled" or "failed" or 2 more` + A file input to the model. - The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. + - `type: "input_file"` - - `"in_progress"` + The type of the input item. Always `input_file`. - - `"cancelled"` + - `"input_file"` - - `"failed"` + - `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`. - - `"expired"` + - `"auto"` - - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` + - `"low"` - The details of the run step. + - `"high"` - - `MessageCreationStepDetails object { message_creation, type }` + - `file_data: optional string` - Details of the message creation by the run step. + The content of the file to be sent to the model. - - `message_creation: object { message_id }` + - `file_id: optional string` - - `message_id: string` + The ID of the file to be sent to the model. - The ID of the message that was created by this run step. + - `file_url: optional string` - - `type: "message_creation"` + The URL of the file to be sent to the model. - Always `message_creation`. + - `filename: optional string` - - `"message_creation"` + The name of the file to be sent to the model. - - `ToolCallsStepDetails object { tool_calls, type }` + - `prompt_cache_breakpoint: optional object { mode }` - Details of the 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. - - `tool_calls: array of ToolCall` + - `mode: "explicit"` - 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 breakpoint mode. Always `explicit`. - - `CodeInterpreterToolCall object { id, code_interpreter, type }` + - `"explicit"` - Details of the Code Interpreter tool call the run step was involved in. + - `role: "user" or "assistant" or "system" or "developer"` - - `id: string` + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - The ID of the tool call. + - `"user"` - - `code_interpreter: object { input, outputs }` + - `"assistant"` - The Code Interpreter tool call definition. + - `"system"` - - `input: string` + - `"developer"` - The input to the Code Interpreter tool call. + - `phase: optional "commentary" or "final_answer"` - - `outputs: array of object { logs, type } or object { image, 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. - 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. + - `"commentary"` - - `Logs object { logs, type }` + - `"final_answer"` - Text output from the Code Interpreter tool call as part of a run step. + - `type: optional "message"` - - `logs: string` + The type of the message input. Always `message`. - The text output from the Code Interpreter tool call. + - `"message"` - - `type: "logs"` + - `Message object { content, role, agent, 2 more }` - Always `logs`. + 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. - - `"logs"` + - `content: BetaResponseInputMessageContentList` - - `Image object { image, type }` + A list of one or many input items to the model, containing different content + types. - - `image: object { file_id }` + - `role: "user" or "system" or "developer"` - - `file_id: string` + The role of the message input. One of `user`, `system`, or `developer`. - The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. + - `"user"` - - `type: "image"` + - `"system"` - Always `image`. + - `"developer"` - - `"image"` + - `agent: optional object { agent_name }` - - `type: "code_interpreter"` + The agent that produced this item. - The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + - `agent_name: string` - - `"code_interpreter"` + The canonical name of the agent that produced this item. - - `FileSearchToolCall object { id, file_search, type }` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `id: string` + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The ID of the tool call object. + - `"in_progress"` - - `file_search: object { ranking_options, results }` + - `"completed"` - For now, this is always going to be an empty object. + - `"incomplete"` - - `ranking_options: optional object { ranker, score_threshold }` + - `type: optional "message"` - The ranking options for the file search. + The type of the message input. Always set to `message`. - - `ranker: "auto" or "default_2024_08_21"` + - `"message"` - The ranker to use for the file search. If not specified will use the `auto` ranker. + - `BetaResponseOutputMessage object { id, content, role, 4 more }` - - `"auto"` + An output message from the model. - - `"default_2024_08_21"` + - `id: string` - - `score_threshold: number` + The unique ID of the output message. - The score threshold for the file search. All values must be a floating point number between 0 and 1. + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - - `results: optional array of object { file_id, file_name, score, content }` + The content of the output message. - The results of the file search. + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - - `file_id: string` + A text output from the model. - The ID of the file that result was found in. + - `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_name: string` + The annotations of the text output. - The name of the file that result was found in. + - `FileCitation object { file_id, filename, index, type }` - - `score: number` + A citation to a file. - The score of the result. All values must be a floating point number between 0 and 1. + - `file_id: string` - - `content: optional array of object { text, type }` + The ID of the file. - The content of the result that was found. The content is only included if requested via the include query parameter. + - `filename: string` - - `text: optional string` + The filename of the file cited. - The text content of the file. + - `index: number` - - `type: optional "text"` + The index of the file in the list of files. - The type of the content. + - `type: "file_citation"` - - `"text"` + The type of the file citation. Always `file_citation`. - - `type: "file_search"` + - `"file_citation"` - The type of tool call. This is always going to be `file_search` for this type of tool call. + - `URLCitation object { end_index, start_index, title, 2 more }` - - `"file_search"` + A citation for a web resource used to generate a model response. - - `FunctionToolCall object { id, function, type }` + - `end_index: number` - - `id: string` + The index of the last character of the URL citation in the message. - The ID of the tool call object. + - `start_index: number` - - `function: object { arguments, name, output }` + The index of the first character of the URL citation in the message. - The definition of the function that was called. + - `title: string` - - `arguments: string` + The title of the web resource. - The arguments passed to the function. + - `type: "url_citation"` - - `name: string` + The type of the URL citation. Always `url_citation`. - The name of the function. + - `"url_citation"` - - `output: string` + - `url: string` - The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. + The URL of the web resource. - - `type: "function"` + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - The type of tool call. This is always going to be `function` for this type of tool call. + A citation for a container file used to generate a model response. - - `"function"` + - `container_id: string` - - `type: "tool_calls"` + The ID of the container file. - Always `tool_calls`. + - `end_index: number` - - `"tool_calls"` + The index of the last character of the container file citation in the message. - - `thread_id: string` + - `file_id: string` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. + The ID of the file. - - `type: "message_creation" or "tool_calls"` + - `filename: string` - The type of run step, which can be either `message_creation` or `tool_calls`. + The filename of the container file cited. - - `"message_creation"` + - `start_index: number` - - `"tool_calls"` + The index of the first character of the container file citation in the message. - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + - `type: "container_file_citation"` - Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. + The type of the container file citation. Always `container_file_citation`. - - `completion_tokens: number` + - `"container_file_citation"` - Number of completion tokens used over the course of the run step. + - `FilePath object { file_id, index, type }` - - `prompt_tokens: number` + A path to a file. - Number of prompt tokens used over the course of the run step. + - `file_id: string` - - `total_tokens: number` + The ID of the file. - Total number of tokens used (prompt + completion). + - `index: number` - - `event: "thread.run.step.created"` + The index of the file in the list of files. - - `"thread.run.step.created"` + - `type: "file_path"` - - `ThreadRunStepInProgress object { data, event }` + The type of the file path. Always `file_path`. - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) moves to an `in_progress` state. + - `"file_path"` - - `data: RunStep` + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - Represents a step in execution of a run. + - `token: string` - - `event: "thread.run.step.in_progress"` + - `bytes: array of number` - - `"thread.run.step.in_progress"` + - `logprob: number` - - `ThreadRunStepDelta object { data, event }` + - `top_logprobs: array of object { token, bytes, logprob }` - Occurs when parts of a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) are being streamed. + - `token: string` - - `data: RunStepDeltaEvent` + - `bytes: array of number` - Represents a run step delta i.e. any changed fields on a run step during streaming. + - `logprob: number` - - `id: string` + - `text: string` - The identifier of the run step, which can be referenced in API endpoints. + The text output from the model. - - `delta: RunStepDelta` + - `type: "output_text"` - The delta containing the fields that have changed on the run step. + The type of the output text. Always `output_text`. - - `step_details: optional RunStepDeltaMessageDelta or ToolCallDeltaObject` + - `"output_text"` - The details of the run step. + - `BetaResponseOutputRefusal object { refusal, type }` - - `RunStepDeltaMessageDelta object { type, message_creation }` + A refusal from the model. - Details of the message creation by the run step. + - `refusal: string` - - `type: "message_creation"` + The refusal explanation from the model. - Always `message_creation`. + - `type: "refusal"` - - `"message_creation"` + The type of the refusal. Always `refusal`. - - `message_creation: optional object { message_id }` + - `"refusal"` - - `message_id: optional string` + - `role: "assistant"` - The ID of the message that was created by this run step. + The role of the output message. Always `assistant`. - - `ToolCallDeltaObject object { type, tool_calls }` + - `"assistant"` - Details of the tool call. + - `status: "in_progress" or "completed" or "incomplete"` - - `type: "tool_calls"` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - Always `tool_calls`. + - `"in_progress"` - - `"tool_calls"` + - `"completed"` - - `tool_calls: optional array of ToolCallDelta` + - `"incomplete"` - 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: "message"` - - `CodeInterpreterToolCallDelta object { index, type, id, code_interpreter }` + The type of the output message. Always `message`. - Details of the Code Interpreter tool call the run step was involved in. + - `"message"` - - `index: number` + - `agent: optional object { agent_name }` - The index of the tool call in the tool calls array. + The agent that produced this item. - - `type: "code_interpreter"` + - `agent_name: string` - The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + The canonical name of the agent that produced this item. - - `"code_interpreter"` + - `phase: optional "commentary" or "final_answer"` - - `id: 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 ID of the tool call. + - `"commentary"` - - `code_interpreter: optional object { input, outputs }` + - `"final_answer"` - The Code Interpreter tool call definition. + - `FileSearchCall object { id, queries, status, 3 more }` - - `input: optional string` + The results of a file search tool call. See the + [file search guide](/docs/guides/tools-file-search) for more information. - The input to the Code Interpreter tool call. + - `id: string` - - `outputs: optional array of CodeInterpreterLogs or CodeInterpreterOutputImage` + The unique ID of the file search 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. + - `queries: array of string` - - `CodeInterpreterLogs object { index, type, logs }` + The queries used to search for files. - Text output from the Code Interpreter tool call as part of a run step. + - `status: "in_progress" or "searching" or "completed" or 2 more` - - `index: number` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - The index of the output in the outputs array. + - `"in_progress"` - - `type: "logs"` + - `"searching"` - Always `logs`. + - `"completed"` - - `"logs"` + - `"incomplete"` - - `logs: optional string` + - `"failed"` - The text output from the Code Interpreter tool call. + - `type: "file_search_call"` - - `CodeInterpreterOutputImage object { index, type, image }` + The type of the file search tool call. Always `file_search_call`. - - `index: number` + - `"file_search_call"` - The index of the output in the outputs array. + - `agent: optional object { agent_name }` - - `type: "image"` + The agent that produced this item. - Always `image`. + - `agent_name: string` - - `"image"` + The canonical name of the agent that produced this item. - - `image: optional object { file_id }` + - `results: optional array of object { attributes, file_id, filename, 2 more }` - - `file_id: optional string` + The results of the file search tool call. - The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. + - `attributes: optional map[string or number or boolean]` - - `FileSearchToolCallDelta object { file_search, index, type, id }` + 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. - - `file_search: unknown` + - `string` - For now, this is always going to be an empty object. + - `number` - - `index: number` + - `boolean` - The index of the tool call in the tool calls array. + - `file_id: optional string` - - `type: "file_search"` + The unique ID of the file. - The type of tool call. This is always going to be `file_search` for this type of tool call. + - `filename: optional string` - - `"file_search"` + The name of the file. - - `id: optional string` + - `score: optional number` - The ID of the tool call object. + The relevance score of the file - a value between 0 and 1. - - `FunctionToolCallDelta object { index, type, id, function }` + - `text: optional string` - - `index: number` + The text that was retrieved from the file. - The index of the tool call in the tool calls array. + - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` - - `type: "function"` + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - The type of tool call. This is always going to be `function` for this type of tool call. + - `id: string` - - `"function"` + The unique ID of the computer call. - - `id: optional string` + - `call_id: string` - The ID of the tool call object. + An identifier used when responding to the tool call with output. - - `function: optional object { arguments, name, output }` + - `pending_safety_checks: array of object { id, code, message }` - The definition of the function that was called. + The pending safety checks for the computer call. - - `arguments: optional string` + - `id: string` - The arguments passed to the function. + The ID of the pending safety check. - - `name: optional string` + - `code: optional string` - The name of the function. + The type of the pending safety check. - - `output: optional string` + - `message: optional string` - The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. + Details about the pending safety check. - - `object: "thread.run.step.delta"` + - `status: "in_progress" or "completed" or "incomplete"` - The object type, which is always `thread.run.step.delta`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"thread.run.step.delta"` + - `"in_progress"` - - `event: "thread.run.step.delta"` + - `"completed"` - - `"thread.run.step.delta"` + - `"incomplete"` - - `ThreadRunStepCompleted object { data, event }` + - `type: "computer_call"` - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is completed. + The type of the computer call. Always `computer_call`. - - `data: RunStep` + - `"computer_call"` - Represents a step in execution of a run. + - `action: optional BetaComputerAction` - - `event: "thread.run.step.completed"` + A click action. - - `"thread.run.step.completed"` + - `Click object { button, type, x, 2 more }` - - `ThreadRunStepFailed object { data, event }` + A click action. - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) fails. + - `button: "left" or "right" or "wheel" or 2 more` - - `data: RunStep` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - Represents a step in execution of a run. + - `"left"` - - `event: "thread.run.step.failed"` + - `"right"` - - `"thread.run.step.failed"` + - `"wheel"` - - `ThreadRunStepCancelled object { data, event }` + - `"back"` - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is cancelled. + - `"forward"` - - `data: RunStep` + - `type: "click"` - Represents a step in execution of a run. + Specifies the event type. For a click action, this property is always `click`. - - `event: "thread.run.step.cancelled"` + - `"click"` - - `"thread.run.step.cancelled"` + - `x: number` - - `ThreadRunStepExpired object { data, event }` + The x-coordinate where the click occurred. - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) expires. + - `y: number` - - `data: RunStep` + The y-coordinate where the click occurred. - Represents a step in execution of a run. + - `keys: optional array of string` - - `event: "thread.run.step.expired"` + The keys being held while clicking. - - `"thread.run.step.expired"` + - `DoubleClick object { keys, type, x, y }` -### Run Stream Event + A double click action. -- `RunStreamEvent = object { data, event } or object { data, event } or object { data, event } or 7 more` + - `keys: array of string` - Occurs when a new [run](https://platform.openai.com/docs/api-reference/runs/object) is created. + The keys being held while double-clicking. - - `ThreadRunCreated object { data, event }` + - `type: "double_click"` - Occurs when a new [run](https://platform.openai.com/docs/api-reference/runs/object) is created. + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `data: Run` + - `"double_click"` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `x: number` - - `id: string` + The x-coordinate where the double click occurred. - The identifier, which can be referenced in API endpoints. + - `y: number` - - `assistant_id: string` + The y-coordinate where the double click occurred. - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + - `Drag object { path, type, keys }` - - `cancelled_at: number` + A drag action. - The Unix timestamp (in seconds) for when the run was cancelled. + - `path: array of object { x, y }` - - `completed_at: number` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - The Unix timestamp (in seconds) for when the run was completed. + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `created_at: number` + - `x: number` - The Unix timestamp (in seconds) for when the run was created. + The x-coordinate. - - `expires_at: number` + - `y: number` - The Unix timestamp (in seconds) for when the run will expire. + The y-coordinate. - - `failed_at: number` + - `type: "drag"` - The Unix timestamp (in seconds) for when the run failed. + Specifies the event type. For a drag action, this property is always set to `drag`. - - `incomplete_details: object { reason }` + - `"drag"` - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + - `keys: optional array of string` - - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` + The keys being held while dragging the mouse. - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + - `Keypress object { keys, type }` - - `"max_completion_tokens"` + A collection of keypresses the model would like to perform. - - `"max_prompt_tokens"` + - `keys: array of string` - - `instructions: string` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `type: "keypress"` - - `last_error: object { code, message }` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - The last error associated with this run. Will be `null` if there are no errors. + - `"keypress"` - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` + - `Move object { type, x, y, keys }` - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + A mouse move action. - - `"server_error"` + - `type: "move"` - - `"rate_limit_exceeded"` + Specifies the event type. For a move action, this property is always set to `move`. - - `"invalid_prompt"` + - `"move"` - - `message: string` + - `x: number` - A human-readable description of the error. + The x-coordinate to move to. - - `max_completion_tokens: number` + - `y: number` - The maximum number of completion tokens specified to have been used over the course of the run. + The y-coordinate to move to. - - `max_prompt_tokens: number` + - `keys: optional array of string` - The maximum number of prompt tokens specified to have been used over the course of the run. + The keys being held while moving the mouse. - - `metadata: Metadata` + - `Screenshot 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. + A screenshot action. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `type: "screenshot"` - - `model: string` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `"screenshot"` - - `object: "thread.run"` + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - The object type, which is always `thread.run`. + A scroll action. - - `"thread.run"` + - `scroll_x: number` - - `parallel_tool_calls: boolean` + The horizontal scroll distance. - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `scroll_y: number` - - `required_action: object { submit_tool_outputs, type }` + The vertical scroll distance. - Details on the action required to continue the run. Will be `null` if no action is required. + - `type: "scroll"` - - `submit_tool_outputs: object { tool_calls }` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - Details on the tool outputs needed for this run to continue. + - `"scroll"` - - `tool_calls: array of RequiredActionFunctionToolCall` + - `x: number` - A list of the relevant tool calls. + The x-coordinate where the scroll occurred. - - `id: string` + - `y: number` - 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](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. + The y-coordinate where the scroll occurred. - - `function: object { arguments, name }` + - `keys: optional array of string` - The function definition. + The keys being held while scrolling. - - `arguments: string` + - `Type object { text, type }` - The arguments that the model expects you to pass to the function. + An action to type in text. - - `name: string` + - `text: string` - The name of the function. + The text to type. - - `type: "function"` + - `type: "type"` - The type of tool call the output is required for. For now, this is always `function`. + Specifies the event type. For a type action, this property is always set to `type`. - - `"function"` + - `"type"` - - `type: "submit_tool_outputs"` + - `Wait object { type }` - For now, this is always `submit_tool_outputs`. + A wait action. - - `"submit_tool_outputs"` + - `type: "wait"` - - `response_format: AssistantResponseFormatOption` + Specifies the event type. For a wait action, this property is always set to `wait`. - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `"wait"` - 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](https://platform.openai.com/docs/guides/structured-outputs). + - `actions: optional BetaComputerActionList` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - **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. + - `Click object { button, type, x, 2 more }` - - `"auto"` + A click action. - `auto` is the default value + - `DoubleClick object { keys, type, x, y }` - - `"auto"` + A double click action. - - `ResponseFormatText object { type }` + - `Drag object { path, type, keys }` - Default response format. Used to generate text responses. + A drag action. - - `type: "text"` + - `Keypress object { keys, type }` - The type of response format being defined. Always `text`. + A collection of keypresses the model would like to perform. - - `"text"` + - `Move object { type, x, y, keys }` - - `ResponseFormatJSONObject object { type }` + A mouse move action. - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + - `Screenshot object { type }` - - `type: "json_object"` + A screenshot action. - The type of response format being defined. Always `json_object`. + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - - `"json_object"` + A scroll action. - - `ResponseFormatJSONSchema object { json_schema, type }` + - `Type object { text, type }` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + An action to type in text. - - `json_schema: object { name, description, schema, strict }` + - `Wait object { type }` - Structured Outputs configuration options, including a JSON Schema. + A wait action. - - `name: string` + - `agent: optional object { agent_name }` - 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 agent that produced this item. - - `description: optional string` + - `agent_name: string` - A description of what the response format is for, used by the model to - determine how to respond in the format. + The canonical name of the agent that produced this item. - - `schema: optional map[unknown]` + - `ComputerCallOutput object { call_id, output, type, 4 more }` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + The output of a computer tool call. - - `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](https://platform.openai.com/docs/guides/structured-outputs). + The ID of the computer tool call that produced the output. - - `type: "json_schema"` + - `output: BetaResponseComputerToolCallOutputScreenshot` - The type of response format being defined. Always `json_schema`. + A computer screenshot image used with the computer use tool. - - `"json_schema"` + - `type: "computer_screenshot"` - - `started_at: number` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - The Unix timestamp (in seconds) for when the run was started. + - `"computer_screenshot"` - - `status: RunStatus` + - `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 identifier of an uploaded file that contains the screenshot. - - `"queued"` + - `image_url: optional string` - - `"in_progress"` + The URL of the screenshot image. - - `"requires_action"` + - `type: "computer_call_output"` - - `"cancelling"` + The type of the computer tool call output. Always `computer_call_output`. - - `"cancelled"` + - `"computer_call_output"` - - `"failed"` + - `id: optional string` - - `"completed"` + The ID of the computer tool call output. - - `"incomplete"` + - `acknowledged_safety_checks: optional array of object { id, code, message }` - - `"expired"` + The safety checks reported by the API that have been acknowledged by the developer. - - `thread_id: string` + - `id: string` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + The ID of the pending safety check. - - `tool_choice: AssistantToolChoiceOption` + - `code: optional 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. + The type of the pending safety check. - - `Auto = "none" or "auto" or "required"` + - `message: optional string` - `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. + Details about the pending safety check. - - `"none"` + - `agent: optional object { agent_name }` - - `"auto"` + The agent that produced this item. - - `"required"` + - `agent_name: string` - - `AssistantToolChoice object { type, function }` + The canonical name of the agent that produced this item. - Specifies a tool the model should use. Use to force the model to call a specific tool. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `type: "function" or "code_interpreter" or "file_search"` + 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 tool. If type is `function`, the function name must be set + - `"in_progress"` - - `"function"` + - `"completed"` - - `"code_interpreter"` + - `"incomplete"` - - `"file_search"` + - `WebSearchCall object { id, action, status, 2 more }` - - `function: optional AssistantToolChoiceFunction` + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. - - `name: string` + - `id: string` - The name of the function to call. + The unique ID of the web search tool call. - - `tools: array of AssistantTool` + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + 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). - - `CodeInterpreterTool object { type }` + - `Search object { type, queries, query, sources }` - - `type: "code_interpreter"` + Action type "search" - Performs a web search query. - The type of tool being defined: `code_interpreter` + - `type: "search"` - - `"code_interpreter"` + The action type. - - `FileSearchTool object { type, file_search }` + - `"search"` - - `type: "file_search"` + - `queries: optional array of string` - The type of tool being defined: `file_search` + The search queries. - - `"file_search"` + - `query: optional string` - - `file_search: optional object { max_num_results, ranking_options }` + The search query. - Overrides for the file search tool. + - `sources: optional array of object { type, url }` - - `max_num_results: optional number` + The sources used in the search. - 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: "url"` - Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + The type of source. Always `url`. - - `ranking_options: optional object { score_threshold, ranker }` + - `"url"` - 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. + - `url: string` - See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + The URL of the source. - - `score_threshold: number` + - `OpenPage object { type, url }` - The score threshold for the file search. All values must be a floating point number between 0 and 1. + Action type "open_page" - Opens a specific URL from search results. - - `ranker: optional "auto" or "default_2024_08_21"` + - `type: "open_page"` - The ranker to use for the file search. If not specified will use the `auto` ranker. + The action type. - - `"auto"` + - `"open_page"` - - `"default_2024_08_21"` + - `url: optional string` - - `FunctionTool object { function, type }` + The URL opened by the model. - - `function: FunctionDefinition` + - `FindInPage object { pattern, type, url }` - - `name: string` + Action type "find_in_page": Searches for a pattern within a loaded page. - 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. + - `pattern: string` - - `description: optional string` + The pattern or text to search for within the page. - A description of what the function does, used by the model to choose when and how to call the function. + - `type: "find_in_page"` - - `parameters: optional FunctionParameters` + The action type. - The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + - `"find_in_page"` - Omitting `parameters` defines a function with an empty parameter list. + - `url: string` - - `strict: optional boolean` + The URL of the page searched for the pattern. - 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](https://platform.openai.com/docs/guides/function-calling). + - `status: "in_progress" or "searching" or "completed" or "failed"` - - `type: "function"` + The status of the web search tool call. - The type of tool being defined: `function` + - `"in_progress"` - - `"function"` + - `"searching"` - - `truncation_strategy: object { type, last_messages }` + - `"completed"` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `"failed"` - - `type: "auto" or "last_messages"` + - `type: "web_search_call"` - 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 type of the web search tool call. Always `web_search_call`. - - `"auto"` + - `"web_search_call"` - - `"last_messages"` + - `agent: optional object { agent_name }` - - `last_messages: optional number` + The agent that produced this item. - The number of most recent messages from the thread when constructing the context for the run. + - `agent_name: string` - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + The canonical name of the agent that produced this item. - 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.). + - `FunctionCall object { arguments, call_id, name, 6 more }` - - `completion_tokens: number` + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. - Number of completion tokens used over the course of the run. + - `arguments: string` - - `prompt_tokens: number` + A JSON string of the arguments to pass to the function. - Number of prompt tokens used over the course of the run. + - `call_id: string` - - `total_tokens: number` + The unique ID of the function tool call generated by the model. - Total number of tokens used (prompt + completion). + - `name: string` - - `temperature: optional number` + The name of the function to run. - The sampling temperature used for this run. If not set, defaults to 1. + - `type: "function_call"` - - `top_p: optional number` + The type of the function tool call. Always `function_call`. - The nucleus sampling value used for this run. If not set, defaults to 1. + - `"function_call"` - - `event: "thread.run.created"` + - `id: optional string` - - `"thread.run.created"` + The unique ID of the function tool call. - - `ThreadRunQueued object { data, event }` + - `agent: optional object { agent_name }` - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to a `queued` status. + The agent that produced this item. - - `data: Run` + - `agent_name: string` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + The canonical name of the agent that produced this item. - - `event: "thread.run.queued"` + - `caller: optional object { type } or object { caller_id, type }` - - `"thread.run.queued"` + The execution context that produced this tool call. - - `ThreadRunInProgress object { data, event }` + - `Direct object { type }` - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to an `in_progress` status. + - `type: "direct"` - - `data: Run` + - `"direct"` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `Program object { caller_id, type }` - - `event: "thread.run.in_progress"` + - `caller_id: string` - - `"thread.run.in_progress"` + The call ID of the program item that produced this tool call. - - `ThreadRunRequiresAction object { data, event }` + - `type: "program"` - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to a `requires_action` status. + - `"program"` - - `data: Run` + - `namespace: optional string` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + The namespace of the function to run. - - `event: "thread.run.requires_action"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"thread.run.requires_action"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `ThreadRunCompleted object { data, event }` + - `"in_progress"` - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) is completed. + - `"completed"` - - `data: Run` + - `"incomplete"` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `FunctionCallOutput object { call_id, output, type, 4 more }` - - `event: "thread.run.completed"` + The output of a function tool call. - - `"thread.run.completed"` + - `call_id: string` - - `ThreadRunIncomplete object { data, event }` + The unique ID of the function tool call generated by the model. - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) ends with status `incomplete`. + - `output: string or array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` - - `data: Run` + Text, image, or file output of the function tool call. - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `string` - - `event: "thread.run.incomplete"` + A JSON string of the output of the function tool call. - - `"thread.run.incomplete"` + - `array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` - - `ThreadRunFailed object { data, event }` + An array of content outputs (text, image, file) for the function tool call. - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) fails. + - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` - - `data: Run` + A text input to the model. - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `text: string` - - `event: "thread.run.failed"` + The text input to the model. - - `"thread.run.failed"` + - `type: "input_text"` - - `ThreadRunCancelling object { data, event }` + The type of the input item. Always `input_text`. - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to a `cancelling` status. + - `"input_text"` - - `data: Run` + - `prompt_cache_breakpoint: optional object { mode }` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `event: "thread.run.cancelling"` + - `mode: "explicit"` - - `"thread.run.cancelling"` + The breakpoint mode. Always `explicit`. - - `ThreadRunCancelled object { data, event }` + - `"explicit"` - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) is cancelled. + - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` - - `data: Run` + An image input to the model. Learn about [image inputs](/docs/guides/vision) - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `type: "input_image"` - - `event: "thread.run.cancelled"` + The type of the input item. Always `input_image`. - - `"thread.run.cancelled"` + - `"input_image"` - - `ThreadRunExpired object { data, event }` + - `detail: optional "low" or "high" or "auto" or "original"` - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) expires. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `data: Run` + - `"low"` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `"high"` - - `event: "thread.run.expired"` + - `"auto"` - - `"thread.run.expired"` + - `"original"` -### Thread Stream Event + - `file_id: optional string` -- `ThreadStreamEvent object { data, event, enabled }` + The ID of the file to be sent to the model. - Occurs when a new [thread](https://platform.openai.com/docs/api-reference/threads/object) is created. + - `image_url: optional string` - - `data: Thread` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). + - `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 identifier, which can be referenced in API endpoints. + - `mode: "explicit"` - - `created_at: number` + The breakpoint mode. Always `explicit`. - The Unix timestamp (in seconds) for when the thread was created. + - `"explicit"` - - `metadata: Metadata` + - `BetaResponseInputFileContent object { type, detail, file_data, 4 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. + A file input to the model. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `type: "input_file"` - - `object: "thread"` + The type of the input item. Always `input_file`. - The object type, which is always `thread`. + - `"input_file"` - - `"thread"` + - `detail: optional "auto" or "low" or "high"` - - `tool_resources: object { code_interpreter, file_search }` + 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 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. + - `"auto"` - - `code_interpreter: optional object { file_ids }` + - `"low"` - - `file_ids: optional array of string` + - `"high"` - A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. + - `file_data: optional string` - - `file_search: optional object { vector_store_ids }` + The base64-encoded data of the file to be sent to the model. - - `vector_store_ids: optional array of string` + - `file_id: optional string` - The [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this thread. There can be a maximum of 1 vector store attached to the thread. + The ID of the file to be sent to the model. - - `event: "thread.created"` + - `file_url: optional string` - - `"thread.created"` + The URL of the file to be sent to the model. - - `enabled: optional boolean` + - `filename: optional string` - Whether to enable input audio transcription. + The name of the file to be sent to the model. -# Threads + - `prompt_cache_breakpoint: optional object { mode }` -## Create thread + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. -**post** `/threads` + - `mode: "explicit"` -Create thread + The breakpoint mode. Always `explicit`. -### Body Parameters + - `"explicit"` -- `messages: optional array of object { content, role, attachments, metadata }` + - `type: "function_call_output"` - A list of [messages](https://platform.openai.com/docs/api-reference/messages) to start the thread with. + The type of the function tool call output. Always `function_call_output`. - - `content: string or array of MessageContentPartParam` + - `"function_call_output"` - The text contents of the message. + - `id: optional string` - - `TextContent = string` + The unique ID of the function tool call output. Populated when this item is returned via API. - The text contents of the message. + - `agent: optional object { agent_name }` - - `ArrayOfContentParts = array of MessageContentPartParam` + The agent that produced this item. - 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](https://platform.openai.com/docs/models). + - `agent_name: string` - - `ImageFileContentBlock object { image_file, type }` + The canonical name of the agent that produced this item. - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + - `caller: optional object { type } or object { caller_id, type }` - - `image_file: ImageFile` + The execution context that produced this tool call. - - `file_id: string` + - `Direct object { type }` - The [File](https://platform.openai.com/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. + - `type: "direct"` - - `detail: optional "auto" or "low" or "high"` + The caller type. Always `direct`. - 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`. + - `"direct"` - - `"auto"` + - `Program object { caller_id, type }` - - `"low"` + - `caller_id: string` - - `"high"` + The call ID of the program item that produced this tool call. - - `type: "image_file"` + - `type: "program"` - Always `image_file`. + The caller type. Always `program`. - - `"image_file"` + - `"program"` - - `ImageURLContentBlock object { image_url, type }` + - `status: optional "in_progress" or "completed" or "incomplete"` - References an image URL in the content of a message. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - `image_url: ImageURL` + - `"in_progress"` - - `url: string` + - `"completed"` - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `"incomplete"` - - `detail: optional "auto" or "low" or "high"` + - `AgentMessage object { author, content, recipient, 3 more }` - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + A message routed between agents. - - `"auto"` + - `author: string` - - `"low"` + The sending agent identity. - - `"high"` + - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` - - `type: "image_url"` + Plaintext, image, or encrypted content sent between agents. - The type of the content part. + - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` - - `"image_url"` + A text input to the model. - - `TextContentBlockParam object { text, type }` + - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` - The text content that is part of a message. + An image input to the model. Learn about [image inputs](/docs/guides/vision) - - `text: string` + - `EncryptedContent object { encrypted_content, type }` - Text content to be sent to the model + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `type: "text"` + - `encrypted_content: string` - Always `text`. + Opaque encrypted content. - - `"text"` + - `type: "encrypted_content"` - - `role: "user" or "assistant"` + The type of the input item. Always `encrypted_content`. - The role of the entity that is creating the message. Allowed values include: + - `"encrypted_content"` - - `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. + - `recipient: string` - - `"user"` + The destination agent identity. - - `"assistant"` + - `type: "agent_message"` - - `attachments: optional array of object { file_id, tools }` + The item type. Always `agent_message`. - A list of files attached to the message, and the tools they should be added to. + - `"agent_message"` - - `file_id: optional string` + - `id: optional string` - The ID of the file to attach to the message. + The unique ID of this agent message item. - - `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` - - `type: "code_interpreter"` + The canonical name of the agent that produced this item. - The type of tool being defined: `code_interpreter` + - `MultiAgentCall object { action, arguments, call_id, 3 more }` - - `"code_interpreter"` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `FileSearch object { type }` + The multi-agent action that was executed. - - `type: "file_search"` + - `"spawn_agent"` - The type of tool being defined: `file_search` + - `"interrupt_agent"` - - `"file_search"` + - `"list_agents"` - - `metadata: optional Metadata` + - `"send_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. + - `"followup_task"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `"wait_agent"` -- `metadata: optional Metadata` + - `arguments: 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 action arguments as a JSON string. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `call_id: string` -- `tool_resources: optional object { code_interpreter, file_search }` + The unique ID linking this call to its output. - 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. + - `type: "multi_agent_call"` - - `code_interpreter: optional object { file_ids }` + The item type. Always `multi_agent_call`. - - `file_ids: optional array of string` + - `"multi_agent_call"` - A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. + - `id: optional string` - - `file_search: optional object { vector_store_ids, vector_stores }` + The unique ID of this multi-agent call. - - `vector_store_ids: optional array of string` + - `agent: optional object { agent_name }` - The [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this thread. There can be a maximum of 1 vector store attached to the thread. + The agent that produced this item. - - `vector_stores: optional array of object { chunking_strategy, file_ids, metadata }` + - `agent_name: string` - A helper to create a [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) with file_ids and attach it to this thread. There can be a maximum of 1 vector store attached to the thread. + The canonical name of the agent that produced this item. - - `chunking_strategy: optional object { type } or object { static, type }` + - `MultiAgentCallOutput object { action, call_id, output, 3 more }` - The chunking strategy used to chunk the file(s). If not set, will use the `auto` strategy. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `Auto object { type }` + The multi-agent action that produced this result. - The default strategy. This strategy currently uses a `max_chunk_size_tokens` of `800` and `chunk_overlap_tokens` of `400`. + - `"spawn_agent"` - - `type: "auto"` + - `"interrupt_agent"` - Always `auto`. + - `"list_agents"` - - `"auto"` + - `"send_message"` - - `Static object { static, type }` + - `"followup_task"` - - `static: object { chunk_overlap_tokens, max_chunk_size_tokens }` + - `"wait_agent"` - - `chunk_overlap_tokens: number` + - `call_id: string` - The number of tokens that overlap between chunks. The default value is `400`. + The unique ID of the multi-agent call. - Note that the overlap must not exceed half of `max_chunk_size_tokens`. + - `output: array of object { text, type, annotations }` - - `max_chunk_size_tokens: number` + Text output returned by the multi-agent action. - The maximum number of tokens in each chunk. The default value is `800`. The minimum value is `100` and the maximum value is `4096`. + - `text: string` - - `type: "static"` + The text content. - Always `static`. + - `type: "output_text"` - - `"static"` + The content type. Always `output_text`. - - `file_ids: optional array of string` + - `"output_text"` - A list of [file](https://platform.openai.com/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. + - `annotations: optional array of object { file_id, filename, index, type } or array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` - - `metadata: optional Metadata` + Citations associated with the text 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. + - `array of object { file_id, filename, index, type }` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `file_id: string` -### Returns + The ID of the file. -- `Thread object { id, created_at, metadata, 2 more }` + - `filename: string` - Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). + The filename of the file cited. - - `id: string` + - `index: number` - The identifier, which can be referenced in API endpoints. + The index of the file in the list of files. - - `created_at: number` + - `type: "file_citation"` - The Unix timestamp (in seconds) for when the thread was created. + The citation type. Always `file_citation`. - - `metadata: Metadata` + - `"file_citation"` - 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. + - `array of object { end_index, start_index, title, 2 more }` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `end_index: number` - - `object: "thread"` + The index of the last character of the citation in the message. - The object type, which is always `thread`. + - `start_index: number` - - `"thread"` + The index of the first character of the citation in the message. - - `tool_resources: object { code_interpreter, file_search }` + - `title: string` - 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. + The title of the cited resource. - - `code_interpreter: optional object { file_ids }` + - `type: "url_citation"` - - `file_ids: optional array of string` + The citation type. Always `url_citation`. - A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. + - `"url_citation"` - - `file_search: optional object { vector_store_ids }` + - `url: string` - - `vector_store_ids: optional array of string` + The URL of the cited resource. - The [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this thread. There can be a maximum of 1 vector store attached to the thread. + - `array of object { container_id, end_index, file_id, 3 more }` -### Example + - `container_id: string` -```http -curl https://api.openai.com/v1/threads \ - -X POST \ - -H 'OpenAI-Beta: assistants=v2' \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + The ID of the container. -#### Response + - `end_index: number` -```json -{ - "id": "id", - "created_at": 0, - "metadata": { - "foo": "string" - }, - "object": "thread", - "tool_resources": { - "code_interpreter": { - "file_ids": [ - "string" - ] - }, - "file_search": { - "vector_store_ids": [ - "string" - ] - } - } -} -``` + The index of the last character of the citation in the message. -### Empty + - `file_id: string` -```http -curl https://api.openai.com/v1/threads \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "OpenAI-Beta: assistants=v2" \ - -d '' -``` + The ID of the container file. -#### Response + - `filename: string` -```json -{ - "id": "thread_abc123", - "object": "thread", - "created_at": 1699012949, - "metadata": {}, - "tool_resources": {} -} -``` + The filename of the container file cited. -### Messages + - `start_index: number` -```http -curl https://api.openai.com/v1/threads \ --H "Content-Type: application/json" \ --H "Authorization: Bearer $OPENAI_API_KEY" \ --H "OpenAI-Beta: assistants=v2" \ --d '{ - "messages": [{ - "role": "user", - "content": "Hello, what is AI?" - }, { - "role": "user", - "content": "How does AI work? Explain it in simple terms." - }] - }' -``` + The index of the first character of the citation in the message. -#### Response + - `type: "container_file_citation"` -```json -{ - "id": "thread_abc123", - "object": "thread", - "created_at": 1699014083, - "metadata": {}, - "tool_resources": {} -} -``` + The citation type. Always `container_file_citation`. -## Create thread and run + - `"container_file_citation"` -**post** `/threads/runs` + - `type: "multi_agent_call_output"` -Create thread and run + The item type. Always `multi_agent_call_output`. -### Body Parameters + - `"multi_agent_call_output"` -- `assistant_id: string` + - `id: optional string` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) to use to execute this run. + The unique ID of this multi-agent call output. -- `instructions: optional string` + - `agent: optional object { agent_name }` - Override the default system message of the assistant. This is useful for modifying the behavior on a per-run basis. + The agent that produced this item. -- `max_completion_tokens: optional number` + - `agent_name: string` - 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. + The canonical name of the agent that produced this item. -- `max_prompt_tokens: optional number` + - `ToolSearchCall object { arguments, type, id, 4 more }` - 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. + - `arguments: unknown` -- `metadata: optional Metadata` + The arguments supplied to the 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. + - `type: "tool_search_call"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The item type. Always `tool_search_call`. -- `model: optional string or ChatModel` + - `"tool_search_call"` - The ID of the [Model](https://platform.openai.com/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. + - `id: optional string` - - `string` + The unique ID of this tool search call. - - `ChatModel = "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 78 more` + - `agent: optional object { agent_name }` - - `"gpt-5.6-sol"` + The agent that produced this item. - - `"gpt-5.6-terra"` + - `agent_name: string` - - `"gpt-5.6-luna"` + The canonical name of the agent that produced this item. - - `"gpt-5.4"` + - `call_id: optional string` - - `"gpt-5.4-mini"` + The unique ID of the tool search call generated by the model. - - `"gpt-5.4-nano"` + - `execution: optional "server" or "client"` - - `"gpt-5.4-mini-2026-03-17"` + Whether tool search was executed by the server or by the client. - - `"gpt-5.4-nano-2026-03-17"` + - `"server"` - - `"gpt-5.3-chat-latest"` + - `"client"` - - `"gpt-5.2"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"gpt-5.2-2025-12-11"` + The status of the tool search call. - - `"gpt-5.2-chat-latest"` + - `"in_progress"` - - `"gpt-5.2-pro"` + - `"completed"` - - `"gpt-5.2-pro-2025-12-11"` + - `"incomplete"` - - `"gpt-5.1"` + - `ToolSearchOutput object { tools, type, id, 4 more }` - - `"gpt-5.1-2025-11-13"` + - `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.1-codex"` + The loaded tool definitions returned by the tool search output. - - `"gpt-5.1-mini"` + - `Function object { name, parameters, strict, 5 more }` - - `"gpt-5.1-chat-latest"` + 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"` + - `name: string` - - `"gpt-5-mini"` + The name of the function to call. - - `"gpt-5-nano"` + - `parameters: map[unknown]` - - `"gpt-5-2025-08-07"` + A JSON schema object describing the parameters of the function. - - `"gpt-5-mini-2025-08-07"` + - `strict: boolean` - - `"gpt-5-nano-2025-08-07"` + Whether strict parameter validation is enforced for this function tool. - - `"gpt-5-chat-latest"` + - `type: "function"` - - `"gpt-4.1"` + The type of the function tool. Always `function`. - - `"gpt-4.1-mini"` + - `"function"` - - `"gpt-4.1-nano"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"gpt-4.1-2025-04-14"` + The tool invocation context(s). - - `"gpt-4.1-mini-2025-04-14"` + - `"direct"` - - `"gpt-4.1-nano-2025-04-14"` + - `"programmatic"` - - `"o4-mini"` + - `defer_loading: optional boolean` - - `"o4-mini-2025-04-16"` + Whether this function is deferred and loaded via tool search. - - `"o3"` + - `description: optional string` - - `"o3-2025-04-16"` + A description of the function. Used by the model to determine whether or not to call the function. - - `"o3-mini"` + - `output_schema: optional map[unknown]` - - `"o3-mini-2025-01-31"` + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `"o1"` + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - - `"o1-2024-12-17"` + 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-preview"` + - `type: "file_search"` - - `"o1-preview-2024-09-12"` + The type of the file search tool. Always `file_search`. - - `"o1-mini"` + - `"file_search"` - - `"o1-mini-2024-09-12"` + - `vector_store_ids: array of string` - - `"gpt-4o"` + The IDs of the vector stores to search. - - `"gpt-4o-2024-11-20"` + - `filters: optional object { key, type, value } or object { filters, type }` - - `"gpt-4o-2024-08-06"` + A filter to apply. - - `"gpt-4o-2024-05-13"` + - `ComparisonFilter object { key, type, value }` - - `"gpt-4o-audio-preview"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `"gpt-4o-audio-preview-2024-10-01"` + - `key: string` - - `"gpt-4o-audio-preview-2024-12-17"` + The key to compare against the value. - - `"gpt-4o-audio-preview-2025-06-03"` + - `type: "eq" or "ne" or "gt" or 5 more` - - `"gpt-4o-mini-audio-preview"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `"gpt-4o-mini-audio-preview-2024-12-17"` + - `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-4o-search-preview"` + - `"eq"` - - `"gpt-4o-mini-search-preview"` + - `"ne"` - - `"gpt-4o-search-preview-2025-03-11"` + - `"gt"` - - `"gpt-4o-mini-search-preview-2025-03-11"` + - `"gte"` - - `"chatgpt-4o-latest"` + - `"lt"` - - `"codex-mini-latest"` + - `"lte"` - - `"gpt-4o-mini"` + - `"in"` - - `"gpt-4o-mini-2024-07-18"` + - `"nin"` - - `"gpt-4-turbo"` + - `value: string or number or boolean or array of string or number` - - `"gpt-4-turbo-2024-04-09"` + The value to compare against the attribute key; supports string, number, or boolean types. - - `"gpt-4-0125-preview"` + - `string` - - `"gpt-4-turbo-preview"` + - `number` - - `"gpt-4-1106-preview"` + - `boolean` - - `"gpt-4-vision-preview"` + - `array of string or number` - - `"gpt-4"` + - `string` - - `"gpt-4-0314"` + - `number` - - `"gpt-4-0613"` + - `CompoundFilter object { filters, type }` - - `"gpt-4-32k"` + Combine multiple filters using `and` or `or`. - - `"gpt-4-32k-0314"` + - `filters: array of object { key, type, value } or unknown` - - `"gpt-4-32k-0613"` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `"gpt-3.5-turbo"` + - `ComparisonFilter object { key, type, value }` - - `"gpt-3.5-turbo-16k"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `"gpt-3.5-turbo-0301"` + - `key: string` - - `"gpt-3.5-turbo-0613"` + The key to compare against the value. - - `"gpt-3.5-turbo-1106"` + - `type: "eq" or "ne" or "gt" or 5 more` - - `"gpt-3.5-turbo-0125"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `"gpt-3.5-turbo-16k-0613"` + - `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 -- `parallel_tool_calls: optional boolean` + - `"eq"` - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `"ne"` -- `response_format: optional AssistantResponseFormatOption` + - `"gt"` - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `"gte"` - 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](https://platform.openai.com/docs/guides/structured-outputs). + - `"lt"` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `"lte"` - **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. + - `"in"` - - `"auto"` + - `"nin"` - `auto` is the default value + - `value: string or number or boolean or array of string or number` - - `"auto"` + The value to compare against the attribute key; supports string, number, or boolean types. - - `ResponseFormatText object { type }` + - `string` - Default response format. Used to generate text responses. + - `number` - - `type: "text"` + - `boolean` - The type of response format being defined. Always `text`. + - `array of string or number` - - `"text"` + - `string` - - `ResponseFormatJSONObject object { type }` + - `number` - 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. + - `unknown` - - `type: "json_object"` + - `type: "and" or "or"` - The type of response format being defined. Always `json_object`. + Type of operation: `and` or `or`. - - `"json_object"` + - `"and"` - - `ResponseFormatJSONSchema object { json_schema, type }` + - `"or"` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `max_num_results: optional number` - - `json_schema: object { name, description, schema, strict }` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - Structured Outputs configuration options, including a JSON Schema. + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `name: string` + Ranking options for 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. + - `hybrid_search: optional object { embedding_weight, text_weight }` - - `description: optional string` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `embedding_weight: number` - - `schema: optional map[unknown]` + The weight of the embedding in the reciprocal ranking fusion. - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `text_weight: number` - - `strict: optional boolean` + The weight of the text in the reciprocal ranking fusion. - 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](https://platform.openai.com/docs/guides/structured-outputs). + - `ranker: optional "auto" or "default-2024-11-15"` - - `type: "json_schema"` + The ranker to use for the file search. - The type of response format being defined. Always `json_schema`. + - `"auto"` - - `"json_schema"` + - `"default-2024-11-15"` -- `stream: optional boolean` + - `score_threshold: optional number` - 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. + 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. -- `temperature: optional number` + - `Computer object { type }` - 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 that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). -- `thread: optional object { messages, metadata, tool_resources }` + - `type: "computer"` - Options to create a new thread. If no thread is provided when running a - request, an empty thread will be created. + The type of the computer tool. Always `computer`. - - `messages: optional array of object { content, role, attachments, metadata }` + - `"computer"` - A list of [messages](https://platform.openai.com/docs/api-reference/messages) to start the thread with. + - `ComputerUsePreview object { display_height, display_width, environment, type }` - - `content: string or array of MessageContentPartParam` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The text contents of the message. + - `display_height: number` - - `TextContent = string` + The height of the computer display. - The text contents of the message. + - `display_width: number` - - `ArrayOfContentParts = array of MessageContentPartParam` + The width of the computer display. - 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](https://platform.openai.com/docs/models). + - `environment: "windows" or "mac" or "linux" or 2 more` - - `ImageFileContentBlock object { image_file, type }` + The type of computer environment to control. - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + - `"windows"` - - `image_file: ImageFile` + - `"mac"` - - `file_id: string` + - `"linux"` - The [File](https://platform.openai.com/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. + - `"ubuntu"` - - `detail: optional "auto" or "low" or "high"` + - `"browser"` - 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: "computer_use_preview"` - - `"auto"` + The type of the computer use tool. Always `computer_use_preview`. - - `"low"` + - `"computer_use_preview"` - - `"high"` + - `WebSearch object { type, filters, search_context_size, user_location }` - - `type: "image_file"` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - Always `image_file`. + - `type: "web_search" or "web_search_2025_08_26"` - - `"image_file"` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `ImageURLContentBlock object { image_url, type }` + - `"web_search"` - References an image URL in the content of a message. + - `"web_search_2025_08_26"` - - `image_url: ImageURL` + - `filters: optional object { allowed_domains }` - - `url: string` + Filters for the search. - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `allowed_domains: optional array of string` - - `detail: optional "auto" or "low" or "high"` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `"auto"` + - `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"` - - `type: "image_url"` + - `user_location: optional object { city, country, region, 2 more }` - The type of the content part. + The approximate location of the user. - - `"image_url"` + - `city: optional string` - - `TextContentBlockParam object { text, type }` + Free text input for the city of the user, e.g. `San Francisco`. - The text content that is part of a message. + - `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`. - Text content to be sent to the model + - `region: optional string` - - `type: "text"` + Free text input for the region of the user, e.g. `California`. - Always `text`. + - `timezone: optional string` - - `"text"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `role: "user" or "assistant"` + - `type: optional "approximate"` - The role of the entity that is creating the message. Allowed values include: + The type of location approximation. Always `approximate`. - - `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. + - `"approximate"` - - `"user"` + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `"assistant"` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - - `attachments: optional array of object { file_id, tools }` + - `server_label: string` - A list of files attached to the message, and the tools they should be added to. + A label for this MCP server, used to identify it in tool calls. - - `file_id: optional string` + - `type: "mcp"` - The ID of the file to attach to the message. + The type of the MCP tool. Always `mcp`. - - `tools: optional array of CodeInterpreterTool or object { type }` + - `"mcp"` - The tools to add this file to. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `CodeInterpreterTool object { type }` + The tool invocation context(s). - - `type: "code_interpreter"` + - `"direct"` - The type of tool being defined: `code_interpreter` + - `"programmatic"` - - `"code_interpreter"` + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `FileSearch object { type }` + List of allowed tool names or a filter object. - - `type: "file_search"` + - `McpAllowedTools = array of string` - The type of tool being defined: `file_search` + A string array of allowed tool names - - `"file_search"` + - `McpToolFilter object { read_only, tool_names }` - - `metadata: optional Metadata` + A filter object to specify which tools are allowed. - 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. + - `read_only: optional boolean` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + 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. - - `metadata: optional Metadata` + - `tool_names: optional array of string` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + List of allowed tool names. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `authorization: optional string` - - `tool_resources: optional object { code_interpreter, file_search }` + 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 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. + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `code_interpreter: optional object { file_ids }` + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). - - `file_ids: optional array of string` + Currently supported `connector_id` values are: - A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with 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` - - `file_search: optional object { vector_store_ids, vector_stores }` + - `"connector_dropbox"` - - `vector_store_ids: optional array of string` + - `"connector_gmail"` - The [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this thread. There can be a maximum of 1 vector store attached to the thread. + - `"connector_googlecalendar"` - - `vector_stores: optional array of object { chunking_strategy, file_ids, metadata }` + - `"connector_googledrive"` - A helper to create a [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) with file_ids and attach it to this thread. There can be a maximum of 1 vector store attached to the thread. + - `"connector_microsoftteams"` - - `chunking_strategy: optional object { type } or object { static, type }` + - `"connector_outlookcalendar"` - The chunking strategy used to chunk the file(s). If not set, will use the `auto` strategy. + - `"connector_outlookemail"` - - `Auto object { type }` + - `"connector_sharepoint"` - The default strategy. This strategy currently uses a `max_chunk_size_tokens` of `800` and `chunk_overlap_tokens` of `400`. + - `defer_loading: optional boolean` - - `type: "auto"` + Whether this MCP tool is deferred and discovered via tool search. - Always `auto`. + - `headers: optional map[string]` - - `"auto"` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `Static object { static, type }` + - `require_approval: optional object { always, never } or "always" or "never"` - - `static: object { chunk_overlap_tokens, max_chunk_size_tokens }` + Specify which of the MCP server's tools require approval. - - `chunk_overlap_tokens: number` + - `McpToolApprovalFilter object { always, never }` - The number of tokens that overlap between chunks. The default value is `400`. + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - Note that the overlap must not exceed half of `max_chunk_size_tokens`. + - `always: optional object { read_only, tool_names }` - - `max_chunk_size_tokens: number` + A filter object to specify which tools are allowed. - The maximum number of tokens in each chunk. The default value is `800`. The minimum value is `100` and the maximum value is `4096`. + - `read_only: optional boolean` - - `type: "static"` + 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. - Always `static`. + - `tool_names: optional array of string` - - `"static"` + List of allowed tool names. - - `file_ids: optional array of string` + - `never: optional object { read_only, tool_names }` - A list of [file](https://platform.openai.com/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. + A filter object to specify which tools are allowed. - - `metadata: optional Metadata` + - `read_only: optional 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. + 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. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `tool_names: optional array of string` -- `tool_choice: optional AssistantToolChoiceOption` + List of allowed tool names. - 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. + - `McpToolApprovalSetting = "always" or "never"` - - `Auto = "none" or "auto" or "required"` + 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. -- `tool_resources: optional object { code_interpreter, file_search }` + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - 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. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `code_interpreter: optional object { file_ids }` + - `type: "auto"` + + Always `auto`. + + - `"auto"` - `file_ids: optional array of string` - A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. + An optional list of uploaded files to make available to your code. - - `file_search: optional object { vector_store_ids }` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `vector_store_ids: optional array of string` + The memory limit for the code interpreter container. - The ID of the [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. + - `"1g"` -- `tools: optional array of AssistantTool` + - `"4g"` - Override the tools the assistant can use for this run. This is useful for modifying the behavior on a per-run basis. + - `"16g"` - - `CodeInterpreterTool object { type }` + - `"64g"` - - `FileSearchTool object { type, file_search }` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `type: "file_search"` + Network access policy for the container. - The type of tool being defined: `file_search` + - `BetaContainerNetworkPolicyDisabled object { type }` - - `"file_search"` + - `type: "disabled"` - - `file_search: optional object { max_num_results, ranking_options }` + Disable outbound network access. Always `disabled`. - Overrides for the file search tool. + - `"disabled"` - - `max_num_results: optional number` + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - 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. + - `allowed_domains: array of string` - Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + A list of allowed domains when type is `allowlist`. - - `ranking_options: optional object { score_threshold, ranker }` + - `type: "allowlist"` - 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. + Allow outbound network access only to specified domains. Always `allowlist`. - See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `"allowlist"` - - `score_threshold: number` + - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` - The score threshold for the file search. All values must be a floating point number between 0 and 1. + Optional domain-scoped secrets for allowlisted domains. - - `ranker: optional "auto" or "default_2024_08_21"` + - `domain: string` - The ranker to use for the file search. If not specified will use the `auto` ranker. + The domain associated with the secret. - - `"auto"` + - `name: string` - - `"default_2024_08_21"` + The name of the secret to inject for the domain. - - `FunctionTool object { function, type }` + - `value: string` - - `function: FunctionDefinition` + The secret value to inject for the domain. - - `name: string` + - `type: "code_interpreter"` - 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 type of the code interpreter tool. Always `code_interpreter`. - - `description: optional string` + - `"code_interpreter"` - A description of what the function does, used by the model to choose when and how to call the function. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `parameters: optional FunctionParameters` + The tool invocation context(s). - The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + - `"direct"` - Omitting `parameters` defines a function with an empty parameter list. + - `"programmatic"` - - `strict: optional boolean` + - `ProgrammaticToolCalling object { 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](https://platform.openai.com/docs/guides/function-calling). + - `type: "programmatic_tool_calling"` - - `type: "function"` + The type of the tool. Always `programmatic_tool_calling`. - The type of tool being defined: `function` + - `"programmatic_tool_calling"` - - `"function"` + - `ImageGeneration object { type, action, background, 9 more }` -- `top_p: optional number` + A tool that generates images using the GPT image models. - 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: "image_generation"` - We generally recommend altering this or temperature but not both. + The type of the image generation tool. Always `image_generation`. -- `truncation_strategy: optional object { type, last_messages }` + - `"image_generation"` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `action: optional "generate" or "edit" or "auto"` - - `type: "auto" or "last_messages"` + Whether to generate a new image or edit an existing image. Default: `auto`. - 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`. + - `"generate"` + + - `"edit"` - `"auto"` - - `"last_messages"` + - `background: optional "transparent" or "opaque" or "auto"` - - `last_messages: optional number` + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - The number of most recent messages from the thread when constructing the context for the run. + - `"transparent"` -### Returns + - `"opaque"` -- `Run object { id, assistant_id, cancelled_at, 24 more }` + - `"auto"` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `input_fidelity: optional "high" or "low"` - - `id: string` + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - The identifier, which can be referenced in API endpoints. + - `"high"` - - `assistant_id: string` + - `"low"` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + - `input_image_mask: optional object { file_id, image_url }` - - `cancelled_at: number` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - The Unix timestamp (in seconds) for when the run was cancelled. + - `file_id: optional string` - - `completed_at: number` + File ID for the mask image. - The Unix timestamp (in seconds) for when the run was completed. + - `image_url: optional string` - - `created_at: number` + Base64-encoded mask image. - The Unix timestamp (in seconds) for when the run was created. + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `expires_at: number` + The image generation model to use. Default: `gpt-image-1`. - The Unix timestamp (in seconds) for when the run will expire. + - `string` - - `failed_at: number` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - The Unix timestamp (in seconds) for when the run failed. + The image generation model to use. Default: `gpt-image-1`. - - `incomplete_details: object { reason }` + - `"gpt-image-1"` - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + - `"gpt-image-1-mini"` - - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` + - `"gpt-image-1.5"` - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + - `moderation: optional "auto" or "low"` - - `"max_completion_tokens"` + Moderation level for the generated image. Default: `auto`. - - `"max_prompt_tokens"` + - `"auto"` - - `instructions: string` + - `"low"` - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `output_compression: optional number` - - `last_error: object { code, message }` + Compression level for the output image. Default: 100. - The last error associated with this run. Will be `null` if there are no errors. + - `output_format: optional "png" or "webp" or "jpeg"` - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + - `"png"` - - `"server_error"` + - `"webp"` - - `"rate_limit_exceeded"` + - `"jpeg"` - - `"invalid_prompt"` + - `partial_images: optional number` - - `message: string` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - A human-readable description of the error. + - `quality: optional "low" or "medium" or "high" or "auto"` - - `max_completion_tokens: number` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - The maximum number of completion tokens specified to have been used over the course of the run. + - `"low"` - - `max_prompt_tokens: number` + - `"medium"` - The maximum number of prompt tokens specified to have been used over the course of the run. + - `"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. + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + 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`. - - `model: string` + - `string` - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `object: "thread.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`. - The object type, which is always `thread.run`. + - `"1024x1024"` - - `"thread.run"` + - `"1024x1536"` - - `parallel_tool_calls: boolean` + - `"1536x1024"` - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `"auto"` - - `required_action: object { submit_tool_outputs, type }` + - `LocalShell object { type }` - Details on the action required to continue the run. Will be `null` if no action is required. + A tool that allows the model to execute shell commands in a local environment. - - `submit_tool_outputs: object { tool_calls }` + - `type: "local_shell"` - Details on the tool outputs needed for this run to continue. + The type of the local shell tool. Always `local_shell`. - - `tool_calls: array of RequiredActionFunctionToolCall` + - `"local_shell"` - A list of the relevant tool calls. + - `Shell object { type, allowed_callers, environment }` - - `id: string` + A tool that allows the model to execute shell commands. - 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](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. + - `type: "shell"` - - `function: object { arguments, name }` + The type of the shell tool. Always `shell`. - The function definition. + - `"shell"` - - `arguments: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The arguments that the model expects you to pass to the function. + The tool invocation context(s). - - `name: string` + - `"direct"` - The name of the function. + - `"programmatic"` - - `type: "function"` + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - The type of tool call the output is required for. For now, this is always `function`. + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - - `"function"` + - `type: "container_auto"` - - `type: "submit_tool_outputs"` + Automatically creates a container for this request - For now, this is always `submit_tool_outputs`. + - `"container_auto"` - - `"submit_tool_outputs"` + - `file_ids: optional array of string` - - `response_format: AssistantResponseFormatOption` + An optional list of uploaded files to make available to your code. - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - 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](https://platform.openai.com/docs/guides/structured-outputs). + The memory limit for the container. - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `"1g"` - **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. + - `"4g"` - - `"auto"` + - `"16g"` - `auto` is the default value + - `"64g"` - - `"auto"` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `ResponseFormatText object { type }` + Network access policy for the container. - Default response format. Used to generate text responses. + - `BetaContainerNetworkPolicyDisabled object { type }` - - `type: "text"` + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - 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. - - `ResponseFormatJSONObject object { type }` + - `BetaSkillReference object { skill_id, type, version }` - 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. + - `skill_id: string` - - `type: "json_object"` + The ID of the referenced skill. - The type of response format being defined. Always `json_object`. + - `type: "skill_reference"` - - `"json_object"` + References a skill created with the /v1/skills endpoint. - - `ResponseFormatJSONSchema object { json_schema, type }` + - `"skill_reference"` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `version: optional string` - - `json_schema: object { name, description, schema, strict }` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - Structured Outputs configuration options, including a JSON Schema. + - `BetaInlineSkill object { description, name, source, type }` + + - `description: string` + + The description of the skill. - `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 skill. - - `description: optional string` + - `source: BetaInlineSkillSource` - A description of what the response format is for, used by the model to - determine how to respond in the format. + Inline skill payload - - `schema: optional map[unknown]` + - `data: string` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + Base64-encoded skill zip bundle. - - `strict: optional boolean` + - `media_type: "application/zip"` - 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](https://platform.openai.com/docs/guides/structured-outputs). + The media type of the inline skill payload. Must be `application/zip`. - - `type: "json_schema"` + - `"application/zip"` - The type of response format being defined. Always `json_schema`. + - `type: "base64"` - - `"json_schema"` + The type of the inline skill source. Must be `base64`. - - `started_at: number` + - `"base64"` - The Unix timestamp (in seconds) for when the run was started. + - `type: "inline"` - - `status: RunStatus` + Defines an inline skill for this request. - The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. + - `"inline"` - - `"queued"` + - `BetaLocalEnvironment object { type, skills }` - - `"in_progress"` + - `type: "local"` - - `"requires_action"` + Use a local computer environment. - - `"cancelling"` + - `"local"` - - `"cancelled"` + - `skills: optional array of BetaLocalSkill` - - `"failed"` + An optional list of skills. - - `"completed"` + - `description: string` - - `"incomplete"` + The description of the skill. - - `"expired"` + - `name: string` - - `thread_id: string` + The name of the skill. - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + - `path: string` - - `tool_choice: AssistantToolChoiceOption` + The path to the directory containing the skill. - 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. + - `BetaContainerReference object { container_id, type }` - - `Auto = "none" or "auto" or "required"` + - `container_id: string` - `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 ID of the referenced container. - - `"none"` + - `type: "container_reference"` - - `"auto"` + References a container created with the /v1/containers endpoint - - `"required"` + - `"container_reference"` - - `AssistantToolChoice object { type, function }` + - `Custom object { name, type, allowed_callers, 3 more }` - Specifies a tool the model should use. Use to force the model to call a specific tool. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `type: "function" or "code_interpreter" or "file_search"` + - `name: string` - The type of the tool. If type is `function`, the function name must be set + The name of the custom tool, used to identify it in tool calls. - - `"function"` + - `type: "custom"` - - `"code_interpreter"` + The type of the custom tool. Always `custom`. - - `"file_search"` + - `"custom"` - - `function: optional AssistantToolChoiceFunction` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `name: string` + The tool invocation context(s). - The name of the function to call. + - `"direct"` - - `tools: array of AssistantTool` + - `"programmatic"` - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `defer_loading: optional boolean` - - `CodeInterpreterTool object { type }` + Whether this tool should be deferred and discovered via tool search. - - `type: "code_interpreter"` + - `description: optional string` - The type of tool being defined: `code_interpreter` + Optional description of the custom tool, used to provide more context. - - `"code_interpreter"` + - `format: optional object { type } or object { definition, syntax, type }` - - `FileSearchTool object { type, file_search }` + The input format for the custom tool. Default is unconstrained text. - - `type: "file_search"` + - `Text object { type }` - The type of tool being defined: `file_search` + Unconstrained free-form text. - - `"file_search"` + - `type: "text"` - - `file_search: optional object { max_num_results, ranking_options }` + Unconstrained text format. Always `text`. - Overrides for the file search tool. + - `"text"` - - `max_num_results: optional number` + - `Grammar object { definition, syntax, 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 grammar defined by the user. + + - `definition: string` - Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + The grammar definition. - - `ranking_options: optional object { score_threshold, ranker }` + - `syntax: "lark" or "regex"` - 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 syntax of the grammar definition. One of `lark` or `regex`. - See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `"lark"` - - `score_threshold: number` + - `"regex"` - The score threshold for the file search. All values must be a floating point number between 0 and 1. + - `type: "grammar"` - - `ranker: optional "auto" or "default_2024_08_21"` + Grammar format. Always `grammar`. - The ranker to use for the file search. If not specified will use the `auto` ranker. + - `"grammar"` - - `"auto"` + - `Namespace object { description, name, tools, type }` - - `"default_2024_08_21"` + Groups function/custom tools under a shared namespace. - - `FunctionTool object { function, type }` + - `description: string` - - `function: FunctionDefinition` + A description of the namespace shown to the model. - `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 namespace name used in tool calls (for example, `crm`). - - `description: optional string` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - A description of what the function does, used by the model to choose when and how to call the function. + The function/custom tools available inside this namespace. - - `parameters: optional FunctionParameters` + - `Function object { name, type, allowed_callers, 5 more }` - The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + - `name: string` - Omitting `parameters` defines a function with an empty parameter list. + - `type: "function"` - - `strict: optional boolean` + - `"function"` - 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](https://platform.openai.com/docs/guides/function-calling). + - `allowed_callers: optional array of "direct" or "programmatic"` - - `type: "function"` + The tool invocation context(s). - The type of tool being defined: `function` + - `"direct"` - - `"function"` + - `"programmatic"` - - `truncation_strategy: object { type, last_messages }` + - `defer_loading: optional boolean` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + Whether this function should be deferred and discovered via tool search. - - `type: "auto" or "last_messages"` + - `description: optional string` - 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`. + - `output_schema: optional map[unknown]` - - `"auto"` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `"last_messages"` + - `parameters: optional unknown` - - `last_messages: optional number` + - `strict: optional boolean` - The number of most recent messages from the thread when constructing the context for the run. + 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. - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + - `Custom object { name, type, allowed_callers, 3 more }` - 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.). + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `completion_tokens: number` + - `name: string` - Number of completion tokens used over the course of the run. + The name of the custom tool, used to identify it in tool calls. - - `prompt_tokens: number` + - `type: "custom"` - Number of prompt tokens used over the course of the run. + The type of the custom tool. Always `custom`. - - `total_tokens: number` + - `"custom"` - Total number of tokens used (prompt + completion). + - `allowed_callers: optional array of "direct" or "programmatic"` - - `temperature: optional number` + The tool invocation context(s). - The sampling temperature used for this run. If not set, defaults to 1. + - `"direct"` - - `top_p: optional number` + - `"programmatic"` - The nucleus sampling value used for this run. If not set, defaults to 1. + - `defer_loading: optional boolean` -### Example + Whether this tool should be deferred and discovered via tool search. -```http -curl https://api.openai.com/v1/threads/runs \ - -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 - }' -``` + - `description: optional string` -#### Response + Optional description of the custom tool, used to provide more context. -```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 -} -``` + - `format: optional object { type } or object { definition, syntax, type }` -### Example + The input format for the custom tool. Default is unconstrained text. -```http -curl https://api.openai.com/v1/threads/runs \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "Content-Type: application/json" \ - -H "OpenAI-Beta: assistants=v2" \ - -d '{ - "assistant_id": "asst_abc123", - "thread": { - "messages": [ - {"role": "user", "content": "Explain deep learning to a 5 year old."} - ] - } - }' -``` + - `Text object { type }` -#### Response + Unconstrained free-form text. -```json -{ - "id": "run_abc123", - "object": "thread.run", - "created_at": 1699076792, - "assistant_id": "asst_abc123", - "thread_id": "thread_abc123", - "status": "queued", - "started_at": null, - "expires_at": 1699077392, - "cancelled_at": null, - "failed_at": null, - "completed_at": null, - "required_action": null, - "last_error": null, - "model": "gpt-4o", - "instructions": "You are a helpful assistant.", - "tools": [], - "tool_resources": {}, - "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: "text"` -### Streaming + Unconstrained text format. Always `text`. -```http -curl https://api.openai.com/v1/threads/runs \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "Content-Type: application/json" \ - -H "OpenAI-Beta: assistants=v2" \ - -d '{ - "assistant_id": "asst_123", - "thread": { - "messages": [ - {"role": "user", "content": "Hello"} - ] - }, - "stream": true - }' -``` + - `"text"` -#### Response + - `Grammar object { definition, syntax, type }` -```json -event: thread.created -data: {"id":"thread_123","object":"thread","created_at":1710348075,"metadata":{}} + A grammar defined by the user. -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":[],"tool_resources":{},"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} + - `definition: string` -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":[],"tool_resources":{},"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 grammar definition. -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":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":[],"tool_resources":{},"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} + - `syntax: "lark" or "regex"` -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} + The syntax of the grammar definition. One of `lark` or `regex`. -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} + - `"lark"` -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":{}} + - `"regex"` -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":{}} + - `type: "grammar"` -event: thread.message.delta -data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"Hello","annotations":[]}}]}} + Grammar format. Always `grammar`. -... + - `"grammar"` -event: thread.message.delta -data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" today"}}]}} + - `type: "namespace"` -event: thread.message.delta -data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"?"}}]}} + The type of the tool. Always `namespace`. -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":{}} + - `"namespace"` -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}} + - `ToolSearch object { type, description, execution, parameters }` -event: thread.run.completed -{"id":"run_123","object":"thread.run","created_at":1710348076,"assistant_id":"asst_123","thread_id":"thread_123","status":"completed","started_at":1713226836,"expires_at":null,"cancelled_at":null,"failed_at":null,"completed_at":1713226837,"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":345,"completion_tokens":11,"total_tokens":356},"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true} + Hosted or BYOT tool search configuration for deferred tools. -event: done -data: [DONE] -``` + - `type: "tool_search"` -### Streaming with Functions + The type of the tool. Always `tool_search`. -```http -curl https://api.openai.com/v1/threads/runs \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "Content-Type: application/json" \ - -H "OpenAI-Beta: assistants=v2" \ - -d '{ - "assistant_id": "asst_abc123", - "thread": { - "messages": [ - {"role": "user", "content": "What is the weather like in San Francisco?"} - ] - }, - "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 - }' -``` + - `"tool_search"` -#### Response + - `description: optional string` -```json -event: thread.created -data: {"id":"thread_123","object":"thread","created_at":1710351818,"metadata":{}} + Description shown to the model for a client-executed tool search tool. -event: thread.run.created -data: {"id":"run_123","object":"thread.run","created_at":1710351818,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710352418,"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}} + - `execution: optional "server" or "client"` -event: thread.run.queued -data: {"id":"run_123","object":"thread.run","created_at":1710351818,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710352418,"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}} + Whether tool search is executed by the server or by the client. -event: thread.run.in_progress -data: {"id":"run_123","object":"thread.run","created_at":1710351818,"assistant_id":"asst_123","thread_id":"thread_123","status":"in_progress","started_at":1710351818,"expires_at":1710352418,"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}} + - `"server"` -event: thread.run.step.created -data: {"id":"step_001","object":"thread.run.step","created_at":1710351819,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"tool_calls","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710352418,"failed_at":null,"last_error":null,"step_details":{"type":"tool_calls","tool_calls":[]},"usage":null} + - `"client"` -event: thread.run.step.in_progress -data: {"id":"step_001","object":"thread.run.step","created_at":1710351819,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"tool_calls","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710352418,"failed_at":null,"last_error":null,"step_details":{"type":"tool_calls","tool_calls":[]},"usage":null} + - `parameters: optional unknown` -event: thread.run.step.delta -data: {"id":"step_001","object":"thread.run.step.delta","delta":{"step_details":{"type":"tool_calls","tool_calls":[{"index":0,"id":"call_XXNp8YGaFrjrSjgqxtC8JJ1B","type":"function","function":{"name":"get_current_weather","arguments":"","output":null}}]}}} + Parameter schema for a client-executed tool search tool. -event: thread.run.step.delta -data: {"id":"step_001","object":"thread.run.step.delta","delta":{"step_details":{"type":"tool_calls","tool_calls":[{"index":0,"type":"function","function":{"arguments":"{\""}}]}}} + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` -event: thread.run.step.delta -data: {"id":"step_001","object":"thread.run.step.delta","delta":{"step_details":{"type":"tool_calls","tool_calls":[{"index":0,"type":"function","function":{"arguments":"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"` -event: thread.run.step.delta -data: {"id":"step_001","object":"thread.run.step.delta","delta":{"step_details":{"type":"tool_calls","tool_calls":[{"index":0,"type":"function","function":{"arguments":"ahrenheit"}}]}}} + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. -event: thread.run.step.delta -data: {"id":"step_001","object":"thread.run.step.delta","delta":{"step_details":{"type":"tool_calls","tool_calls":[{"index":0,"type":"function","function":{"arguments":"\"}"}}]}}} + - `"web_search_preview"` -event: thread.run.requires_action -data: {"id":"run_123","object":"thread.run","created_at":1710351818,"assistant_id":"asst_123","thread_id":"thread_123","status":"requires_action","started_at":1710351818,"expires_at":1710352418,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":{"type":"submit_tool_outputs","submit_tool_outputs":{"tool_calls":[{"id":"call_XXNp8YGaFrjrSjgqxtC8JJ1B","type":"function","function":{"name":"get_current_weather","arguments":"{\"location\":\"San Francisco, CA\",\"unit\":\"fahrenheit\"}"}}]}},"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":345,"completion_tokens":11,"total_tokens":356},"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + - `"web_search_preview_2025_03_11"` -event: done -data: [DONE] -``` + - `search_content_types: optional array of "text" or "image"` -## Retrieve thread + - `"text"` -**get** `/threads/{thread_id}` + - `"image"` -Retrieve thread + - `search_context_size: optional "low" or "medium" or "high"` -### Path Parameters + 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_id: string` + - `"low"` -### Returns + - `"medium"` -- `Thread object { id, created_at, metadata, 2 more }` + - `"high"` - Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). + - `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"` - - `created_at: number` + The type of location approximation. Always `approximate`. - The Unix timestamp (in seconds) for when the thread was created. + - `"approximate"` - - `metadata: Metadata` + - `city: 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. + Free text input for the city of the user, e.g. `San Francisco`. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `country: optional string` - - `object: "thread"` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The object type, which is always `thread`. + - `region: optional string` - - `"thread"` + Free text input for the region of the user, e.g. `California`. - - `tool_resources: object { code_interpreter, file_search }` + - `timezone: optional string` - 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. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `code_interpreter: optional object { file_ids }` + - `ApplyPatch object { type, allowed_callers }` - - `file_ids: optional array of string` + Allows the assistant to create, delete, or update files using unified diffs. - A list of [file](https://platform.openai.com/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: "apply_patch"` - - `file_search: optional object { vector_store_ids }` + The type of the tool. Always `apply_patch`. - - `vector_store_ids: optional array of string` + - `"apply_patch"` - The [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this thread. There can be a maximum of 1 vector store attached to the thread. + - `allowed_callers: optional array of "direct" or "programmatic"` -### Example + The tool invocation context(s). -```http -curl https://api.openai.com/v1/threads/$THREAD_ID \ - -H 'OpenAI-Beta: assistants=v2' \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + - `"direct"` -#### Response + - `"programmatic"` -```json -{ - "id": "id", - "created_at": 0, - "metadata": { - "foo": "string" - }, - "object": "thread", - "tool_resources": { - "code_interpreter": { - "file_ids": [ - "string" - ] - }, - "file_search": { - "vector_store_ids": [ - "string" - ] - } - } -} -``` + - `type: "tool_search_output"` -### Example + The item type. Always `tool_search_output`. -```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" -``` + - `"tool_search_output"` -#### Response + - `id: optional string` -```json -{ - "id": "thread_abc123", - "object": "thread", - "created_at": 1699014083, - "metadata": {}, - "tool_resources": { - "code_interpreter": { - "file_ids": [] - } - } -} -``` + The unique ID of this tool search output. -## Modify thread + - `agent: optional object { agent_name }` -**post** `/threads/{thread_id}` + The agent that produced this item. -Modify thread + - `agent_name: string` -### Path Parameters + The canonical name of the agent that produced this item. -- `thread_id: string` + - `call_id: optional string` -### Body Parameters + The unique ID of the tool search call generated by the model. -- `metadata: optional Metadata` + - `execution: optional "server" or "client"` - 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 tool search was executed by the server or by the client. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `"server"` -- `tool_resources: optional object { code_interpreter, file_search }` + - `"client"` - 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. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `code_interpreter: optional object { file_ids }` + The status of the tool search output. - - `file_ids: optional array of string` + - `"in_progress"` - A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. + - `"completed"` - - `file_search: optional object { vector_store_ids }` + - `"incomplete"` - - `vector_store_ids: optional array of string` + - `AdditionalTools object { role, tools, type, 2 more }` - The [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this thread. There can be a maximum of 1 vector store attached to the thread. + - `role: "developer"` -### Returns + The role that provided the additional tools. Only `developer` is supported. -- `Thread object { id, created_at, metadata, 2 more }` + - `"developer"` - Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). + - `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` + A list of additional tools made available at this item. - The identifier, which can be referenced in API endpoints. + - `Function object { name, parameters, strict, 5 more }` - - `created_at: 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 Unix timestamp (in seconds) for when the thread was created. + - `name: string` - - `metadata: Metadata` + The name of the function to 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. + - `parameters: map[unknown]` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + A JSON schema object describing the parameters of the function. - - `object: "thread"` + - `strict: boolean` - The object type, which is always `thread`. + Whether strict parameter validation is enforced for this function tool. - - `"thread"` + - `type: "function"` - - `tool_resources: object { code_interpreter, file_search }` + The type of the function tool. Always `function`. - 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. + - `"function"` - - `code_interpreter: optional object { file_ids }` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `file_ids: optional array of string` + The tool invocation context(s). - A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. + - `"direct"` - - `file_search: optional object { vector_store_ids }` + - `"programmatic"` - - `vector_store_ids: optional array of string` + - `defer_loading: optional boolean` - The [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this thread. There can be a maximum of 1 vector store attached to the thread. + Whether this function is deferred and loaded via tool search. -### Example + - `description: optional string` -```http -curl https://api.openai.com/v1/threads/$THREAD_ID \ - -H 'Content-Type: application/json' \ - -H 'OpenAI-Beta: assistants=v2' \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -d '{}' -``` + 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": "id", - "created_at": 0, - "metadata": { - "foo": "string" - }, - "object": "thread", - "tool_resources": { - "code_interpreter": { - "file_ids": [ - "string" - ] - }, - "file_search": { - "vector_store_ids": [ - "string" - ] - } - } -} -``` + A JSON schema object describing the JSON value encoded in string outputs for this function. -### Example + - `FileSearch object { type, vector_store_ids, filters, 2 more }` -```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" \ - -d '{ - "metadata": { - "modified": "true", - "user": "abc123" - } - }' -``` + 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). -#### Response + - `type: "file_search"` -```json -{ - "id": "thread_abc123", - "object": "thread", - "created_at": 1699014083, - "metadata": { - "modified": "true", - "user": "abc123" - }, - "tool_resources": {} -} -``` + The type of the file search tool. Always `file_search`. -## Delete thread + - `"file_search"` -**delete** `/threads/{thread_id}` + - `vector_store_ids: array of string` -Delete thread + The IDs of the vector stores to search. -### Path Parameters + - `filters: optional object { key, type, value } or object { filters, type }` -- `thread_id: string` + A filter to apply. -### Returns + - `ComparisonFilter object { key, type, value }` -- `ThreadDeleted object { id, deleted, object }` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `id: string` + - `key: string` - - `deleted: boolean` + The key to compare against the value. - - `object: "thread.deleted"` + - `type: "eq" or "ne" or "gt" or 5 more` - - `"thread.deleted"` + 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/threads/$THREAD_ID \ - -X DELETE \ - -H 'OpenAI-Beta: assistants=v2' \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + - `"eq"` -#### Response + - `"ne"` -```json -{ - "id": "id", - "deleted": true, - "object": "thread.deleted" -} -``` + - `"gt"` -### Example + - `"gte"` -```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 -``` + - `"lt"` -#### Response + - `"lte"` -```json -{ - "id": "thread_abc123", - "object": "thread.deleted", - "deleted": true -} -``` + - `"in"` -## Domain Types + - `"nin"` -### Assistant Response Format Option + - `value: string or number or boolean or array of string or number` -- `AssistantResponseFormatOption = "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` + The value to compare against the attribute key; supports string, number, or boolean types. - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `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](https://platform.openai.com/docs/guides/structured-outputs). + - `number` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `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. + - `array of string or number` - - `"auto"` + - `string` - `auto` is the default value + - `number` - - `"auto"` + - `CompoundFilter object { filters, type }` - - `ResponseFormatText object { type }` + Combine multiple filters using `and` or `or`. - Default response format. Used to generate text responses. + - `filters: array of object { key, type, value } or unknown` - - `type: "text"` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - The type of response format being defined. Always `text`. + - `ComparisonFilter object { key, type, value }` - - `"text"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `ResponseFormatJSONObject object { type }` + - `key: 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. + The key to compare against the value. - - `type: "json_object"` + - `type: "eq" or "ne" or "gt" or 5 more` - The type of response format being defined. Always `json_object`. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `"json_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 - - `ResponseFormatJSONSchema object { json_schema, type }` + - `"eq"` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `"ne"` - - `json_schema: object { name, description, schema, strict }` + - `"gt"` - Structured Outputs configuration options, including a JSON Schema. + - `"gte"` - - `name: string` + - `"lt"` - 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. + - `"lte"` - - `description: optional string` + - `"in"` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `"nin"` - - `schema: optional map[unknown]` + - `value: string or number or boolean or 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/). + The value to compare against the attribute key; supports string, number, or boolean types. - - `strict: optional boolean` + - `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](https://platform.openai.com/docs/guides/structured-outputs). + - `number` - - `type: "json_schema"` + - `boolean` - The type of response format being defined. Always `json_schema`. + - `array of string or number` - - `"json_schema"` + - `string` -### Assistant Tool Choice + - `number` -- `AssistantToolChoice object { type, function }` + - `unknown` - Specifies a tool the model should use. Use to force the model to call a specific tool. + - `type: "and" or "or"` - - `type: "function" or "code_interpreter" or "file_search"` + Type of operation: `and` or `or`. - The type of the tool. If type is `function`, the function name must be set + - `"and"` - - `"function"` + - `"or"` - - `"code_interpreter"` + - `max_num_results: optional number` - - `"file_search"` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `function: optional AssistantToolChoiceFunction` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `name: string` + Ranking options for search. - The name of the function to call. + - `hybrid_search: optional object { embedding_weight, text_weight }` -### Assistant Tool Choice Function + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. -- `AssistantToolChoiceFunction object { name }` + - `embedding_weight: number` - - `name: string` + The weight of the embedding in the reciprocal ranking fusion. - The name of the function to call. + - `text_weight: number` -### Assistant Tool Choice Option + The weight of the text in the reciprocal ranking fusion. -- `AssistantToolChoiceOption = "none" or "auto" or "required" or AssistantToolChoice` + - `ranker: optional "auto" or "default-2024-11-15"` - 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 ranker to use for the file search. - - `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. + - `"default-2024-11-15"` - - `"none"` + - `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. - - `"required"` + - `Computer object { type }` - - `AssistantToolChoice object { type, function }` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - Specifies a tool the model should use. Use to force the model to call a specific tool. + - `type: "computer"` - - `type: "function" or "code_interpreter" or "file_search"` + The type of the computer tool. Always `computer`. - The type of the tool. If type is `function`, the function name must be set + - `"computer"` - - `"function"` + - `ComputerUsePreview object { display_height, display_width, environment, type }` - - `"code_interpreter"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"file_search"` + - `display_height: number` - - `function: optional AssistantToolChoiceFunction` + The height of the computer display. - - `name: string` + - `display_width: number` - The name of the function to call. + The width of the computer display. -### Thread + - `environment: "windows" or "mac" or "linux" or 2 more` -- `Thread object { id, created_at, metadata, 2 more }` + The type of computer environment to control. - Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). + - `"windows"` - - `id: string` + - `"mac"` - The identifier, which can be referenced in API endpoints. + - `"linux"` - - `created_at: number` + - `"ubuntu"` - The Unix timestamp (in seconds) for when the thread was created. + - `"browser"` - - `metadata: Metadata` + - `type: "computer_use_preview"` - 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 computer use tool. Always `computer_use_preview`. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `"computer_use_preview"` - - `object: "thread"` + - `WebSearch object { type, filters, search_context_size, user_location }` - The object type, which is always `thread`. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - - `"thread"` + - `type: "web_search" or "web_search_2025_08_26"` - - `tool_resources: object { code_interpreter, file_search }` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - 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. + - `"web_search"` - - `code_interpreter: optional object { file_ids }` + - `"web_search_2025_08_26"` - - `file_ids: optional array of string` + - `filters: optional object { allowed_domains }` - A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. + Filters for the search. - - `file_search: optional object { vector_store_ids }` + - `allowed_domains: optional array of string` - - `vector_store_ids: 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. - The [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this thread. There can be a maximum of 1 vector store attached to the thread. + Example: `["pubmed.ncbi.nlm.nih.gov"]` -### Thread Deleted + - `search_context_size: optional "low" or "medium" or "high"` -- `ThreadDeleted object { id, deleted, object }` + 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"` - - `deleted: boolean` + - `"medium"` - - `object: "thread.deleted"` + - `"high"` - - `"thread.deleted"` + - `user_location: optional object { city, country, region, 2 more }` -# Runs + The approximate location of the user. -## List runs + - `city: optional string` -**get** `/threads/{thread_id}/runs` + Free text input for the city of the user, e.g. `San Francisco`. -List runs + - `country: optional string` -### Path Parameters + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. -- `thread_id: string` + - `region: optional string` -### Query Parameters + Free text input for the region of the user, e.g. `California`. -- `after: optional string` + - `timezone: 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. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. -- `before: optional string` + - `type: optional "approximate"` - 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 location approximation. Always `approximate`. -- `limit: optional number` + - `"approximate"` - A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. + - `Mcp object { server_label, type, allowed_callers, 9 more }` -- `order: optional "asc" or "desc"` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. + - `server_label: string` - - `"asc"` + A label for this MCP server, used to identify it in tool calls. - - `"desc"` + - `type: "mcp"` -### Returns + The type of the MCP tool. Always `mcp`. -- `data: array of Run` + - `"mcp"` - - `id: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The identifier, which can be referenced in API endpoints. + The tool invocation context(s). - - `assistant_id: string` + - `"direct"` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + - `"programmatic"` - - `cancelled_at: number` + - `allowed_tools: optional array of string or object { read_only, tool_names }` - The Unix timestamp (in seconds) for when the run was cancelled. + List of allowed tool names or a filter object. - - `completed_at: number` + - `McpAllowedTools = array of string` - The Unix timestamp (in seconds) for when the run was completed. + A string array of allowed tool names - - `created_at: number` + - `McpToolFilter object { read_only, tool_names }` - The Unix timestamp (in seconds) for when the run was created. + A filter object to specify which tools are allowed. - - `expires_at: number` + - `read_only: optional boolean` - The Unix timestamp (in seconds) for when the run will expire. + 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_at: number` + - `tool_names: optional array of string` - The Unix timestamp (in seconds) for when the run failed. + List of allowed tool names. - - `incomplete_details: object { reason }` + - `authorization: optional string` - Details on why the run is incomplete. Will be `null` if the run is not 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. - - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + 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). - - `"max_completion_tokens"` + Currently supported `connector_id` values are: - - `"max_prompt_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` - - `instructions: string` + - `"connector_dropbox"` - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `"connector_gmail"` - - `last_error: object { code, message }` + - `"connector_googlecalendar"` - The last error associated with this run. Will be `null` if there are no errors. + - `"connector_googledrive"` - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` + - `"connector_microsoftteams"` - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + - `"connector_outlookcalendar"` - - `"server_error"` + - `"connector_outlookemail"` - - `"rate_limit_exceeded"` + - `"connector_sharepoint"` - - `"invalid_prompt"` + - `defer_loading: optional boolean` - - `message: string` + Whether this MCP tool is deferred and discovered via tool search. - A human-readable description of the error. + - `headers: optional map[string]` - - `max_completion_tokens: number` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - The maximum number of completion tokens specified to have been used over the course of the run. + - `require_approval: optional object { always, never } or "always" or "never"` - - `max_prompt_tokens: number` + Specify which of the MCP server's tools require approval. - The maximum number of prompt tokens specified to have been used over the course of the run. + - `McpToolApprovalFilter object { always, never }` - - `metadata: Metadata` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - 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: optional object { read_only, tool_names }` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + A filter object to specify which tools are allowed. - - `model: string` + - `read_only: optional boolean` - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for 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. - - `object: "thread.run"` + - `tool_names: optional array of string` - The object type, which is always `thread.run`. + List of allowed tool names. - - `"thread.run"` + - `never: optional object { read_only, tool_names }` - - `parallel_tool_calls: boolean` + A filter object to specify which tools are allowed. - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `read_only: optional boolean` - - `required_action: object { submit_tool_outputs, 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. - Details on the action required to continue the run. Will be `null` if no action is required. + - `tool_names: optional array of string` - - `submit_tool_outputs: object { tool_calls }` + List of allowed tool names. - Details on the tool outputs needed for this run to continue. + - `McpToolApprovalSetting = "always" or "never"` - - `tool_calls: array of RequiredActionFunctionToolCall` + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - A list of the relevant tool calls. + - `"always"` - - `id: string` + - `"never"` - 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](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. + - `server_description: optional string` - - `function: object { arguments, name }` + Optional description of the MCP server, used to provide more context. - The function definition. + - `server_url: optional string` - - `arguments: string` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - The arguments that the model expects you to pass to the function. + - `tunnel_id: optional string` - - `name: 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 name of the function. + - `CodeInterpreter object { container, type, allowed_callers }` - - `type: "function"` + A tool that runs Python code to help generate a response to a prompt. - The type of tool call the output is required for. For now, this is always `function`. + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `"function"` + 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: "submit_tool_outputs"` + - `string` - For now, this is always `submit_tool_outputs`. + The container ID. - - `"submit_tool_outputs"` + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - - `response_format: AssistantResponseFormatOption` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `type: "auto"` - 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](https://platform.openai.com/docs/guides/structured-outputs). + Always `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. + - `file_ids: optional array of string` - - `"auto"` + An optional list of uploaded files to make available to your code. - `auto` is the default value + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `"auto"` + The memory limit for the code interpreter container. - - `ResponseFormatText object { type }` + - `"1g"` - Default response format. Used to generate text responses. + - `"4g"` - - `type: "text"` + - `"16g"` - The type of response format being defined. Always `text`. + - `"64g"` - - `"text"` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `ResponseFormatJSONObject object { type }` + Network access policy for the container. - 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. + - `BetaContainerNetworkPolicyDisabled object { type }` - - `type: "json_object"` + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - The type of response format being defined. Always `json_object`. + - `type: "code_interpreter"` - - `"json_object"` + The type of the code interpreter tool. Always `code_interpreter`. - - `ResponseFormatJSONSchema object { json_schema, type }` + - `"code_interpreter"` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `allowed_callers: optional array of "direct" or "programmatic"` - - `json_schema: object { name, description, schema, strict }` + The tool invocation context(s). - Structured Outputs configuration options, including a JSON Schema. + - `"direct"` - - `name: string` + - `"programmatic"` - 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. + - `ProgrammaticToolCalling object { type }` - - `description: optional string` + - `type: "programmatic_tool_calling"` - 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 tool. Always `programmatic_tool_calling`. - - `schema: optional map[unknown]` + - `"programmatic_tool_calling"` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `ImageGeneration object { type, action, background, 9 more }` - - `strict: optional boolean` + A tool that generates images using the GPT image models. - 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](https://platform.openai.com/docs/guides/structured-outputs). + - `type: "image_generation"` - - `type: "json_schema"` + The type of the image generation tool. Always `image_generation`. - The type of response format being defined. Always `json_schema`. + - `"image_generation"` - - `"json_schema"` + - `action: optional "generate" or "edit" or "auto"` - - `started_at: number` + Whether to generate a new image or edit an existing image. Default: `auto`. - The Unix timestamp (in seconds) for when the run was started. + - `"generate"` - - `status: RunStatus` + - `"edit"` - The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. + - `"auto"` - - `"queued"` + - `background: optional "transparent" or "opaque" or "auto"` - - `"in_progress"` + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - - `"requires_action"` + - `"transparent"` - - `"cancelling"` + - `"opaque"` - - `"cancelled"` + - `"auto"` - - `"failed"` + - `input_fidelity: optional "high" or "low"` - - `"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`. - - `"incomplete"` + - `"high"` - - `"expired"` + - `"low"` - - `thread_id: string` + - `input_image_mask: optional object { file_id, image_url }` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `tool_choice: AssistantToolChoiceOption` + - `file_id: optional 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. + File ID for the mask image. - - `Auto = "none" or "auto" or "required"` + - `image_url: optional string` - `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. + Base64-encoded mask image. - - `"none"` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `"auto"` + The image generation model to use. Default: `gpt-image-1`. - - `"required"` + - `string` - - `AssistantToolChoice object { type, function }` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - Specifies a tool the model should use. Use to force the model to call a specific tool. + The image generation model to use. Default: `gpt-image-1`. - - `type: "function" or "code_interpreter" or "file_search"` + - `"gpt-image-1"` - The type of the tool. If type is `function`, the function name must be set + - `"gpt-image-1-mini"` - - `"function"` + - `"gpt-image-1.5"` - - `"code_interpreter"` + - `moderation: optional "auto" or "low"` - - `"file_search"` + Moderation level for the generated image. Default: `auto`. - - `function: optional AssistantToolChoiceFunction` + - `"auto"` - - `name: string` + - `"low"` - The name of the function to call. + - `output_compression: optional number` - - `tools: array of AssistantTool` + Compression level for the output image. Default: 100. - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `output_format: optional "png" or "webp" or "jpeg"` - - `CodeInterpreterTool object { type }` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `type: "code_interpreter"` + - `"png"` - The type of tool being defined: `code_interpreter` + - `"webp"` - - `"code_interpreter"` + - `"jpeg"` - - `FileSearchTool object { type, file_search }` + - `partial_images: optional number` - - `type: "file_search"` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - The type of tool being defined: `file_search` + - `quality: optional "low" or "medium" or "high" or "auto"` - - `"file_search"` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `file_search: optional object { max_num_results, ranking_options }` + - `"low"` - Overrides for the file search tool. + - `"medium"` - - `max_num_results: optional number` + - `"high"` - 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. + - `"auto"` - Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `ranking_options: optional object { score_threshold, ranker }` + 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 ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. + - `string` - See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `score_threshold: 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 score threshold for the file search. All values must be a floating point number between 0 and 1. + - `"1024x1024"` - - `ranker: optional "auto" or "default_2024_08_21"` + - `"1024x1536"` - The ranker to use for the file search. If not specified will use the `auto` ranker. + - `"1536x1024"` - `"auto"` - - `"default_2024_08_21"` + - `LocalShell object { type }` - - `FunctionTool object { function, type }` + A tool that allows the model to execute shell commands in a local environment. - - `function: FunctionDefinition` + - `type: "local_shell"` - - `name: string` + The type of the local shell tool. Always `local_shell`. - 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. + - `"local_shell"` - - `description: optional string` + - `Shell object { type, allowed_callers, environment }` - A description of what the function does, used by the model to choose when and how to call the function. + A tool that allows the model to execute shell commands. - - `parameters: optional FunctionParameters` + - `type: "shell"` - The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/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 shell tool. Always `shell`. - Omitting `parameters` defines a function with an empty parameter list. + - `"shell"` - - `strict: optional boolean` + - `allowed_callers: optional array of "direct" or "programmatic"` - 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](https://platform.openai.com/docs/guides/function-calling). + The tool invocation context(s). - - `type: "function"` + - `"direct"` - The type of tool being defined: `function` + - `"programmatic"` - - `"function"` + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - `truncation_strategy: object { type, last_messages }` + - `BetaContainerAuto object { type, file_ids, memory_limit, 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. + - `BetaLocalEnvironment object { type, skills }` - - `type: "auto" or "last_messages"` + - `BetaContainerReference object { container_id, type }` - 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 object { name, type, allowed_callers, 3 more }` - - `"auto"` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `"last_messages"` + - `name: string` - - `last_messages: optional number` + The name of the custom tool, used to identify it in tool calls. - The number of most recent messages from the thread when constructing the context for the run. + - `type: "custom"` - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + The type of the custom tool. Always `custom`. - 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.). + - `"custom"` - - `completion_tokens: number` + - `allowed_callers: optional array of "direct" or "programmatic"` - Number of completion tokens used over the course of the run. + The tool invocation context(s). - - `prompt_tokens: number` + - `"direct"` - Number of prompt tokens used over the course of the run. + - `"programmatic"` - - `total_tokens: number` + - `defer_loading: optional boolean` - Total number of tokens used (prompt + completion). + Whether this tool should be deferred and discovered via tool search. - - `temperature: optional number` + - `description: optional string` - The sampling temperature used for this run. If not set, defaults to 1. + Optional description of the custom tool, used to provide more context. - - `top_p: optional number` + - `format: optional object { type } or object { definition, syntax, type }` - The nucleus sampling value used for this run. If not set, defaults to 1. + The input format for the custom tool. Default is unconstrained text. -- `first_id: string` + - `Text object { type }` -- `has_more: boolean` + Unconstrained free-form text. -- `last_id: string` + - `type: "text"` -- `object: string` + Unconstrained text format. Always `text`. -### Example + - `"text"` -```http -curl https://api.openai.com/v1/threads/$THREAD_ID/runs \ - -H 'OpenAI-Beta: assistants=v2' \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + - `Grammar object { definition, syntax, type }` -#### Response + A grammar defined by the user. -```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": [ - { - "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 - } - ], - "first_id": "run_abc123", - "has_more": false, - "last_id": "run_abc456", - "object": "list" -} -``` + - `definition: string` -### Example + The grammar definition. -```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" -``` + - `syntax: "lark" or "regex"` -#### Response + The syntax of the grammar definition. One of `lark` or `regex`. -```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 -} -``` + - `"lark"` -## Create run + - `"regex"` -**post** `/threads/{thread_id}/runs` + - `type: "grammar"` -Create run + Grammar format. Always `grammar`. -### Path Parameters + - `"grammar"` -- `thread_id: string` + - `Namespace object { description, name, tools, type }` -### Query Parameters + Groups function/custom tools under a shared namespace. -- `include: optional array of RunStepInclude` + - `description: 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 description of the namespace shown to the model. - See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `name: string` - - `"step_details.tool_calls[*].file_search.results[*].content"` + The namespace name used in tool calls (for example, `crm`). -### Body Parameters + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` -- `assistant_id: string` + The function/custom tools available inside this namespace. - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) to use to execute this run. + - `Function object { name, type, allowed_callers, 5 more }` -- `additional_instructions: optional string` + - `name: 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. + - `type: "function"` -- `additional_messages: optional array of object { content, role, attachments, metadata }` + - `"function"` - Adds additional messages to the thread before creating the run. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `content: string or array of MessageContentPartParam` + The tool invocation context(s). - The text contents of the message. + - `"direct"` - - `TextContent = string` + - `"programmatic"` - The text contents of the message. + - `defer_loading: optional boolean` - - `ArrayOfContentParts = array of MessageContentPartParam` + Whether this function should be deferred and discovered via tool search. - 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](https://platform.openai.com/docs/models). + - `description: optional string` - - `ImageFileContentBlock object { image_file, type }` + - `output_schema: optional map[unknown]` - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `image_file: ImageFile` + - `parameters: optional unknown` - - `file_id: string` + - `strict: optional boolean` - The [File](https://platform.openai.com/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. + 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. - - `detail: optional "auto" or "low" or "high"` + - `Custom object { name, type, allowed_callers, 3 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`. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `"auto"` + - `name: string` - - `"low"` + The name of the custom tool, used to identify it in tool calls. - - `"high"` + - `type: "custom"` - - `type: "image_file"` + The type of the custom tool. Always `custom`. - Always `image_file`. + - `"custom"` - - `"image_file"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `ImageURLContentBlock object { image_url, type }` + The tool invocation context(s). - References an image URL in the content of a message. + - `"direct"` - - `image_url: ImageURL` + - `"programmatic"` - - `url: string` + - `defer_loading: optional boolean` - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + Whether this tool should be deferred and discovered via tool search. - - `detail: optional "auto" or "low" or "high"` + - `description: optional 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` + Optional description of the custom tool, used to provide more context. - - `"auto"` + - `format: optional object { type } or object { definition, syntax, type }` - - `"low"` + The input format for the custom tool. Default is unconstrained text. - - `"high"` + - `Text object { type }` - - `type: "image_url"` + Unconstrained free-form text. - The type of the content part. + - `type: "text"` - - `"image_url"` + Unconstrained text format. Always `text`. - - `TextContentBlockParam object { text, type }` + - `"text"` - The text content that is part of a message. + - `Grammar object { definition, syntax, type }` - - `text: string` + A grammar defined by the user. - Text content to be sent to the model + - `definition: string` - - `type: "text"` + The grammar definition. - Always `text`. + - `syntax: "lark" or "regex"` - - `"text"` + The syntax of the grammar definition. One of `lark` or `regex`. - - `role: "user" or "assistant"` + - `"lark"` - The role of the entity that is creating the message. Allowed values include: + - `"regex"` - - `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. + - `type: "grammar"` - - `"user"` + Grammar format. Always `grammar`. - - `"assistant"` + - `"grammar"` - - `attachments: optional array of object { file_id, tools }` + - `type: "namespace"` - A list of files attached to the message, and the tools they should be added to. + The type of the tool. Always `namespace`. - - `file_id: optional string` + - `"namespace"` - The ID of the file to attach to the message. + - `ToolSearch object { type, description, execution, parameters }` - - `tools: optional array of CodeInterpreterTool or object { type }` + Hosted or BYOT tool search configuration for deferred tools. - The tools to add this file to. + - `type: "tool_search"` - - `CodeInterpreterTool object { type }` + The type of the tool. Always `tool_search`. - - `type: "code_interpreter"` + - `"tool_search"` - The type of tool being defined: `code_interpreter` + - `description: optional string` - - `"code_interpreter"` + Description shown to the model for a client-executed tool search tool. - - `FileSearch object { type }` + - `execution: optional "server" or "client"` - - `type: "file_search"` + Whether tool search is executed by the server or by the client. - The type of tool being defined: `file_search` + - `"server"` - - `"file_search"` + - `"client"` - - `metadata: optional Metadata` + - `parameters: optional unknown` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + Parameter schema for a client-executed tool search tool. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` -- `instructions: optional string` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - Overrides the [instructions](https://platform.openai.com/docs/api-reference/assistants/createAssistant) of the assistant. This is useful for modifying the behavior on a per-run basis. + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` -- `max_completion_tokens: optional number` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - 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. + - `"web_search_preview"` -- `max_prompt_tokens: optional number` + - `"web_search_preview_2025_03_11"` - 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. + - `search_content_types: optional array of "text" or "image"` -- `metadata: optional Metadata` + - `"text"` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `"image"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `search_context_size: optional "low" or "medium" or "high"` -- `model: optional string or ChatModel` + 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 [Model](https://platform.openai.com/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. + - `"low"` - - `string` + - `"medium"` - - `ChatModel = "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 78 more` + - `"high"` - - `"gpt-5.6-sol"` + - `user_location: optional object { type, city, country, 2 more }` - - `"gpt-5.6-terra"` + The user's location. - - `"gpt-5.6-luna"` + - `type: "approximate"` - - `"gpt-5.4"` + The type of location approximation. Always `approximate`. - - `"gpt-5.4-mini"` + - `"approximate"` - - `"gpt-5.4-nano"` + - `city: optional string` - - `"gpt-5.4-mini-2026-03-17"` + Free text input for the city of the user, e.g. `San Francisco`. - - `"gpt-5.4-nano-2026-03-17"` + - `country: optional string` - - `"gpt-5.3-chat-latest"` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `"gpt-5.2"` + - `region: optional string` - - `"gpt-5.2-2025-12-11"` + Free text input for the region of the user, e.g. `California`. - - `"gpt-5.2-chat-latest"` + - `timezone: optional string` - - `"gpt-5.2-pro"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `"gpt-5.2-pro-2025-12-11"` + - `ApplyPatch object { type, allowed_callers }` - - `"gpt-5.1"` + Allows the assistant to create, delete, or update files using unified diffs. - - `"gpt-5.1-2025-11-13"` + - `type: "apply_patch"` - - `"gpt-5.1-codex"` + The type of the tool. Always `apply_patch`. - - `"gpt-5.1-mini"` + - `"apply_patch"` - - `"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"` + - `type: "additional_tools"` - - `"gpt-5-mini-2025-08-07"` + The item type. Always `additional_tools`. - - `"gpt-5-nano-2025-08-07"` + - `"additional_tools"` - - `"gpt-5-chat-latest"` + - `id: optional string` - - `"gpt-4.1"` + The unique ID of this additional tools item. - - `"gpt-4.1-mini"` + - `agent: optional object { agent_name }` - - `"gpt-4.1-nano"` + The agent that produced this item. - - `"gpt-4.1-2025-04-14"` + - `agent_name: string` - - `"gpt-4.1-mini-2025-04-14"` + The canonical name of the agent that produced this item. - - `"gpt-4.1-nano-2025-04-14"` + - `Reasoning object { id, summary, type, 4 more }` - - `"o4-mini"` + 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). - - `"o4-mini-2025-04-16"` + - `id: string` - - `"o3"` + The unique identifier of the reasoning content. - - `"o3-2025-04-16"` + - `summary: array of object { text, type }` - - `"o3-mini"` + Reasoning summary content. - - `"o3-mini-2025-01-31"` + - `text: string` - - `"o1"` + A summary of the reasoning output from the model so far. - - `"o1-2024-12-17"` + - `type: "summary_text"` - - `"o1-preview"` + The type of the object. Always `summary_text`. - - `"o1-preview-2024-09-12"` + - `"summary_text"` - - `"o1-mini"` + - `type: "reasoning"` - - `"o1-mini-2024-09-12"` + The type of the object. Always `reasoning`. - - `"gpt-4o"` + - `"reasoning"` - - `"gpt-4o-2024-11-20"` + - `agent: optional object { agent_name }` - - `"gpt-4o-2024-08-06"` + The agent that produced this item. - - `"gpt-4o-2024-05-13"` + - `agent_name: string` - - `"gpt-4o-audio-preview"` + The canonical name of the agent that produced this item. - - `"gpt-4o-audio-preview-2024-10-01"` + - `content: optional array of object { text, type }` - - `"gpt-4o-audio-preview-2024-12-17"` + Reasoning text content. - - `"gpt-4o-audio-preview-2025-06-03"` + - `text: string` - - `"gpt-4o-mini-audio-preview"` + The reasoning text from the model. - - `"gpt-4o-mini-audio-preview-2024-12-17"` + - `type: "reasoning_text"` - - `"gpt-4o-search-preview"` + The type of the reasoning text. Always `reasoning_text`. - - `"gpt-4o-mini-search-preview"` + - `"reasoning_text"` - - `"gpt-4o-search-preview-2025-03-11"` + - `encrypted_content: optional string` - - `"gpt-4o-mini-search-preview-2025-03-11"` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - - `"chatgpt-4o-latest"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"codex-mini-latest"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"gpt-4o-mini"` + - `"in_progress"` - - `"gpt-4o-mini-2024-07-18"` + - `"completed"` - - `"gpt-4-turbo"` + - `"incomplete"` - - `"gpt-4-turbo-2024-04-09"` + - `Compaction object { encrypted_content, type, id, agent }` - - `"gpt-4-0125-preview"` + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). - - `"gpt-4-turbo-preview"` + - `encrypted_content: string` - - `"gpt-4-1106-preview"` + The encrypted content of the compaction summary. - - `"gpt-4-vision-preview"` + - `type: "compaction"` - - `"gpt-4"` + The type of the item. Always `compaction`. - - `"gpt-4-0314"` + - `"compaction"` - - `"gpt-4-0613"` + - `id: optional string` - - `"gpt-4-32k"` + The ID of the compaction item. - - `"gpt-4-32k-0314"` + - `agent: optional object { agent_name }` - - `"gpt-4-32k-0613"` + The agent that produced this item. - - `"gpt-3.5-turbo"` + - `agent_name: string` - - `"gpt-3.5-turbo-16k"` + The canonical name of the agent that produced this item. - - `"gpt-3.5-turbo-0301"` + - `ImageGenerationCall object { id, result, status, 2 more }` - - `"gpt-3.5-turbo-0613"` + An image generation request made by the model. - - `"gpt-3.5-turbo-1106"` + - `id: string` - - `"gpt-3.5-turbo-0125"` + The unique ID of the image generation call. - - `"gpt-3.5-turbo-16k-0613"` + - `result: string` -- `parallel_tool_calls: optional boolean` + The generated image encoded in base64. - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `status: "in_progress" or "completed" or "generating" or "failed"` -- `reasoning_effort: optional ReasoningEffort` + The status of the image generation call. - 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"` + - `"generating"` - - `"low"` + - `"failed"` - - `"medium"` + - `type: "image_generation_call"` - - `"high"` + The type of the image generation call. Always `image_generation_call`. - - `"xhigh"` + - `"image_generation_call"` - - `"max"` + - `agent: optional object { agent_name }` -- `response_format: optional AssistantResponseFormatOption` + The agent that produced this item. - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `agent_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](https://platform.openai.com/docs/guides/structured-outputs). + The canonical name of the agent that produced this item. - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `CodeInterpreterCall object { id, code, container_id, 4 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 tool call to run code. - - `"auto"` + - `id: string` - `auto` is the default value + The unique ID of the code interpreter tool call. - - `"auto"` + - `code: string` - - `ResponseFormatText object { type }` + The code to run, or null if not available. - Default response format. Used to generate text responses. + - `container_id: string` - - `type: "text"` + The ID of the container used to run the code. - The type of response format being defined. Always `text`. + - `outputs: array of object { logs, type } or object { type, url }` - - `"text"` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `ResponseFormatJSONObject object { type }` + - `Logs object { logs, 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. + The logs output from the code interpreter. - - `type: "json_object"` + - `logs: string` - The type of response format being defined. Always `json_object`. + The logs output from the code interpreter. - - `"json_object"` + - `type: "logs"` - - `ResponseFormatJSONSchema object { json_schema, type }` + The type of the output. Always `logs`. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `"logs"` - - `json_schema: object { name, description, schema, strict }` + - `Image object { type, url }` - Structured Outputs configuration options, including a JSON Schema. + The image output from the code interpreter. - - `name: string` + - `type: "image"` - 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 output. Always `image`. - - `description: optional string` + - `"image"` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `url: string` - - `schema: optional map[unknown]` + The URL of the image output from the code interpreter. - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - - `strict: optional boolean` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - 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](https://platform.openai.com/docs/guides/structured-outputs). + - `"in_progress"` - - `type: "json_schema"` + - `"completed"` - The type of response format being defined. Always `json_schema`. + - `"incomplete"` - - `"json_schema"` + - `"interpreting"` -- `stream: optional boolean` + - `"failed"` - 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. + - `type: "code_interpreter_call"` -- `temperature: optional number` + The type of the code interpreter tool call. Always `code_interpreter_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. + - `"code_interpreter_call"` -- `tool_choice: optional AssistantToolChoiceOption` + - `agent: optional object { agent_name }` - 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 agent that produced this item. - - `Auto = "none" or "auto" or "required"` + - `agent_name: string` - `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 canonical name of the agent that produced this item. - - `"none"` + - `LocalShellCall object { id, action, call_id, 3 more }` - - `"auto"` + A tool call to run a command on the local shell. - - `"required"` + - `id: string` - - `AssistantToolChoice object { type, function }` + The unique ID of the local shell call. - Specifies a tool the model should use. Use to force the model to call a specific tool. + - `action: object { command, env, type, 3 more }` - - `type: "function" or "code_interpreter" or "file_search"` + Execute a shell command on the server. - The type of the tool. If type is `function`, the function name must be set + - `command: array of string` - - `"function"` + The command to run. - - `"code_interpreter"` + - `env: map[string]` - - `"file_search"` + Environment variables to set for the command. - - `function: optional AssistantToolChoiceFunction` + - `type: "exec"` - - `name: string` + The type of the local shell action. Always `exec`. - The name of the function to call. + - `"exec"` -- `tools: optional array of AssistantTool` + - `timeout_ms: optional number` - Override the tools the assistant can use for this run. This is useful for modifying the behavior on a per-run basis. + Optional timeout in milliseconds for the command. - - `CodeInterpreterTool object { type }` + - `user: optional string` - - `FileSearchTool object { type, file_search }` + Optional user to run the command as. - - `type: "file_search"` + - `working_directory: optional string` - The type of tool being defined: `file_search` + Optional working directory to run the command in. - - `"file_search"` + - `call_id: string` - - `file_search: optional object { max_num_results, ranking_options }` + The unique ID of the local shell tool call generated by the model. - Overrides for the file search tool. + - `status: "in_progress" or "completed" or "incomplete"` - - `max_num_results: optional number` + The status of the local shell call. - 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. + - `"in_progress"` - Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `"completed"` - - `ranking_options: optional object { score_threshold, ranker }` + - `"incomplete"` - 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: "local_shell_call"` - See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + The type of the local shell call. Always `local_shell_call`. - - `score_threshold: number` + - `"local_shell_call"` - The score threshold for the file search. All values must be a floating point number between 0 and 1. + - `agent: optional object { agent_name }` - - `ranker: optional "auto" or "default_2024_08_21"` + The agent that produced this item. - The ranker to use for the file search. If not specified will use the `auto` ranker. + - `agent_name: string` - - `"auto"` + The canonical name of the agent that produced this item. - - `"default_2024_08_21"` + - `LocalShellCallOutput object { id, output, type, 2 more }` - - `FunctionTool object { function, type }` + The output of a local shell tool call. - - `function: FunctionDefinition` + - `id: string` - - `name: string` + The unique ID of the local shell tool call generated by the model. - 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` + A JSON string of the output of the local shell tool call. - A description of what the function does, used by the model to choose when and how to call the function. + - `type: "local_shell_call_output"` - - `parameters: optional FunctionParameters` + The type of the local shell tool call output. Always `local_shell_call_output`. - The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + - `"local_shell_call_output"` - Omitting `parameters` defines a function with an empty parameter list. + - `agent: optional object { agent_name }` - - `strict: optional boolean` + The agent that produced this item. - 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](https://platform.openai.com/docs/guides/function-calling). + - `agent_name: string` - - `type: "function"` + The canonical name of the agent that produced this item. - The type of tool being defined: `function` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"function"` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. -- `top_p: optional number` + - `"in_progress"` - 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. + - `"completed"` - We generally recommend altering this or temperature but not both. + - `"incomplete"` -- `truncation_strategy: optional object { type, last_messages }` + - `ShellCall object { action, call_id, type, 5 more }` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + A tool representing a request to execute one or more shell commands. - - `type: "auto" or "last_messages"` + - `action: object { commands, max_output_length, timeout_ms }` - 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 shell commands and limits that describe how to run the tool call. - - `"auto"` + - `commands: array of string` - - `"last_messages"` + Ordered shell commands for the execution environment to run. - - `last_messages: optional number` + - `max_output_length: optional number` - The number of most recent messages from the thread when constructing the context for the run. + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. -### Returns + - `timeout_ms: optional number` -- `Run object { id, assistant_id, cancelled_at, 24 more }` + Maximum wall-clock time in milliseconds to allow the shell commands to run. - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `call_id: string` - - `id: string` + The unique ID of the shell tool call generated by the model. - The identifier, which can be referenced in API endpoints. + - `type: "shell_call"` - - `assistant_id: string` + The type of the item. Always `shell_call`. - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + - `"shell_call"` - - `cancelled_at: number` + - `id: optional string` - The Unix timestamp (in seconds) for when the run was cancelled. + The unique ID of the shell tool call. Populated when this item is returned via API. - - `completed_at: number` + - `agent: optional object { agent_name }` - The Unix timestamp (in seconds) for when the run was completed. + The agent that produced this item. - - `created_at: number` + - `agent_name: string` - The Unix timestamp (in seconds) for when the run was created. + The canonical name of the agent that produced this item. - - `expires_at: number` + - `caller: optional object { type } or object { caller_id, type }` - The Unix timestamp (in seconds) for when the run will expire. + The execution context that produced this tool call. - - `failed_at: number` + - `Direct object { type }` - The Unix timestamp (in seconds) for when the run failed. + - `type: "direct"` - - `incomplete_details: object { reason }` + The caller type. Always `direct`. - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + - `"direct"` - - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` + - `Program object { caller_id, type }` - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + - `caller_id: string` - - `"max_completion_tokens"` + The call ID of the program item that produced this tool call. - - `"max_prompt_tokens"` + - `type: "program"` - - `instructions: string` + The caller type. Always `program`. - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `"program"` - - `last_error: object { code, message }` + - `environment: optional BetaLocalEnvironment or BetaContainerReference` - The last error associated with this run. Will be `null` if there are no errors. + The environment to execute the shell commands in. - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` + - `BetaLocalEnvironment object { type, skills }` - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + - `BetaContainerReference object { container_id, type }` - - `"server_error"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"rate_limit_exceeded"` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `"invalid_prompt"` + - `"in_progress"` - - `message: string` + - `"completed"` - A human-readable description of the error. + - `"incomplete"` - - `max_completion_tokens: number` + - `ShellCallOutput object { call_id, output, type, 5 more }` - The maximum number of completion tokens specified to have been used over the course of the run. + The streamed output items emitted by a shell tool call. - - `max_prompt_tokens: number` + - `call_id: string` - The maximum number of prompt tokens specified to have been used over the course of the run. + The unique ID of the shell tool call generated by the model. - - `metadata: Metadata` + - `output: array of BetaResponseFunctionShellCallOutputContent` - 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. + Captured chunks of stdout and stderr output, along with their associated outcomes. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `outcome: object { type } or object { exit_code, type }` - - `model: string` + The exit or timeout outcome associated with this shell call. - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `Timeout object { type }` - - `object: "thread.run"` + Indicates that the shell call exceeded its configured time limit. - The object type, which is always `thread.run`. + - `type: "timeout"` - - `"thread.run"` + The outcome type. Always `timeout`. - - `parallel_tool_calls: boolean` + - `"timeout"` - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `Exit object { exit_code, type }` - - `required_action: object { submit_tool_outputs, type }` + Indicates that the shell commands finished and returned an exit code. - Details on the action required to continue the run. Will be `null` if no action is required. + - `exit_code: number` - - `submit_tool_outputs: object { tool_calls }` + The exit code returned by the shell process. - Details on the tool outputs needed for this run to continue. + - `type: "exit"` - - `tool_calls: array of RequiredActionFunctionToolCall` + The outcome type. Always `exit`. - A list of the relevant tool calls. + - `"exit"` - - `id: string` + - `stderr: 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](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. + Captured stderr output for the shell call. - - `function: object { arguments, name }` + - `stdout: string` - The function definition. + Captured stdout output for the shell call. - - `arguments: string` + - `type: "shell_call_output"` - The arguments that the model expects you to pass to the function. + The type of the item. Always `shell_call_output`. - - `name: string` + - `"shell_call_output"` - The name of the function. + - `id: optional string` - - `type: "function"` + The unique ID of the shell tool call output. Populated when this item is returned via API. - The type of tool call the output is required for. For now, this is always `function`. + - `agent: optional object { agent_name }` - - `"function"` + The agent that produced this item. - - `type: "submit_tool_outputs"` + - `agent_name: string` - For now, this is always `submit_tool_outputs`. + The canonical name of the agent that produced this item. - - `"submit_tool_outputs"` + - `caller: optional object { type } or object { caller_id, type }` - - `response_format: AssistantResponseFormatOption` + The execution context that produced this tool call. - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `Direct object { type }` - 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](https://platform.openai.com/docs/guides/structured-outputs). + - `type: "direct"` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + The caller type. Always `direct`. - **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"` + - `Program object { caller_id, type }` - `auto` is the default value + - `caller_id: string` - - `"auto"` + The call ID of the program item that produced this tool call. - - `ResponseFormatText object { type }` + - `type: "program"` - Default response format. Used to generate text responses. + The caller type. Always `program`. - - `type: "text"` + - `"program"` - The type of response format being defined. Always `text`. + - `max_output_length: optional number` - - `"text"` + The maximum number of UTF-8 characters captured for this shell call's combined output. - - `ResponseFormatJSONObject object { type }` + - `status: optional "in_progress" or "completed" or "incomplete"` - 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 status of the shell call output. - - `type: "json_object"` + - `"in_progress"` - The type of response format being defined. Always `json_object`. + - `"completed"` - - `"json_object"` + - `"incomplete"` - - `ResponseFormatJSONSchema object { json_schema, type }` + - `ApplyPatchCall object { call_id, operation, status, 4 more }` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + A tool call representing a request to create, delete, or update files using diff patches. - - `json_schema: object { name, description, schema, strict }` + - `call_id: string` - Structured Outputs configuration options, including a JSON Schema. + The unique ID of the apply patch tool call generated by the model. - - `name: string` + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, 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. + The specific create, delete, or update instruction for the apply_patch tool call. - - `description: optional string` + - `CreateFile object { diff, path, type }` - A description of what the response format is for, used by the model to - determine how to respond in the format. + Instruction for creating a new file via the apply_patch tool. - - `schema: optional map[unknown]` + - `diff: string` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + Unified diff content to apply when creating the file. - - `strict: optional boolean` + - `path: 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](https://platform.openai.com/docs/guides/structured-outputs). + Path of the file to create relative to the workspace root. - - `type: "json_schema"` + - `type: "create_file"` - The type of response format being defined. Always `json_schema`. + The operation type. Always `create_file`. - - `"json_schema"` + - `"create_file"` - - `started_at: number` + - `DeleteFile object { path, type }` - The Unix timestamp (in seconds) for when the run was started. + Instruction for deleting an existing file via the apply_patch tool. - - `status: RunStatus` + - `path: string` - The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. + Path of the file to delete relative to the workspace root. - - `"queued"` + - `type: "delete_file"` - - `"in_progress"` + The operation type. Always `delete_file`. - - `"requires_action"` + - `"delete_file"` - - `"cancelling"` + - `UpdateFile object { diff, path, type }` - - `"cancelled"` + Instruction for updating an existing file via the apply_patch tool. - - `"failed"` + - `diff: string` - - `"completed"` + Unified diff content to apply to the existing file. - - `"incomplete"` + - `path: string` - - `"expired"` + Path of the file to update relative to the workspace root. - - `thread_id: string` + - `type: "update_file"` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + The operation type. Always `update_file`. - - `tool_choice: AssistantToolChoiceOption` + - `"update_file"` - 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. + - `status: "in_progress" or "completed"` - - `Auto = "none" or "auto" or "required"` + The status of the apply patch tool call. One of `in_progress` or `completed`. - `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. + - `"in_progress"` - - `"none"` + - `"completed"` - - `"auto"` + - `type: "apply_patch_call"` - - `"required"` + The type of the item. Always `apply_patch_call`. - - `AssistantToolChoice object { type, function }` + - `"apply_patch_call"` - Specifies a tool the model should use. Use to force the model to call a specific tool. + - `id: optional string` - - `type: "function" or "code_interpreter" or "file_search"` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - The type of the tool. If type is `function`, the function name must be set + - `agent: optional object { agent_name }` - - `"function"` + The agent that produced this item. - - `"code_interpreter"` + - `agent_name: string` - - `"file_search"` + The canonical name of the agent that produced this item. - - `function: optional AssistantToolChoiceFunction` + - `caller: optional object { type } or object { caller_id, type }` - - `name: string` + The execution context that produced this tool call. - The name of the function to call. + - `Direct object { type }` - - `tools: array of AssistantTool` + - `type: "direct"` - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + The caller type. Always `direct`. - - `CodeInterpreterTool object { type }` + - `"direct"` - - `type: "code_interpreter"` + - `Program object { caller_id, type }` - The type of tool being defined: `code_interpreter` + - `caller_id: string` - - `"code_interpreter"` + The call ID of the program item that produced this tool call. - - `FileSearchTool object { type, file_search }` + - `type: "program"` - - `type: "file_search"` + The caller type. Always `program`. - The type of tool being defined: `file_search` + - `"program"` - - `"file_search"` + - `ApplyPatchCallOutput object { call_id, status, type, 4 more }` - - `file_search: optional object { max_num_results, ranking_options }` + The streamed output emitted by an apply patch tool call. - Overrides for the file search tool. + - `call_id: string` - - `max_num_results: optional number` + The unique ID of the apply patch tool call generated by the model. - The maximum number of results 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. + - `status: "completed" or "failed"` - Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + The status of the apply patch tool call output. One of `completed` or `failed`. - - `ranking_options: optional object { score_threshold, ranker }` + - `"completed"` - 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. + - `"failed"` - See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `type: "apply_patch_call_output"` - - `score_threshold: number` + The type of the item. Always `apply_patch_call_output`. - The score threshold for the file search. All values must be a floating point number between 0 and 1. + - `"apply_patch_call_output"` - - `ranker: optional "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 the apply patch tool call output. Populated when this item is returned via API. - - `"auto"` + - `agent: optional object { agent_name }` - - `"default_2024_08_21"` + The agent that produced this item. - - `FunctionTool object { function, type }` + - `agent_name: string` - - `function: FunctionDefinition` + The canonical name of the agent that produced this item. - - `name: string` + - `caller: optional object { type } or object { caller_id, 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 execution context that produced this tool call. - - `description: optional string` + - `Direct object { type }` - A description of what the function does, used by the model to choose when and how to call the function. + - `type: "direct"` - - `parameters: optional FunctionParameters` + The caller type. Always `direct`. - The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + - `"direct"` - Omitting `parameters` defines a function with an empty parameter list. + - `Program object { caller_id, type }` - - `strict: optional boolean` + - `caller_id: 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](https://platform.openai.com/docs/guides/function-calling). + The call ID of the program item that produced this tool call. - - `type: "function"` + - `type: "program"` - The type of tool being defined: `function` + The caller type. Always `program`. - - `"function"` + - `"program"` - - `truncation_strategy: object { type, last_messages }` + - `output: optional string` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - - `type: "auto" or "last_messages"` + - `McpListTools object { id, server_label, tools, 3 more }` - 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`. + A list of tools available on an MCP server. - - `"auto"` + - `id: string` - - `"last_messages"` + The unique ID of the list. - - `last_messages: optional number` + - `server_label: string` - The number of most recent messages from the thread when constructing the context for the run. + The label of the MCP server. - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + - `tools: array of object { input_schema, name, annotations, description }` - 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 tools available on the server. - - `completion_tokens: number` + - `input_schema: unknown` - Number of completion tokens used over the course of the run. + The JSON schema describing the tool's input. - - `prompt_tokens: number` + - `name: string` - Number of prompt tokens used over the course of the run. + The name of the tool. - - `total_tokens: number` + - `annotations: optional unknown` - Total number of tokens used (prompt + completion). + Additional annotations about the tool. - - `temperature: optional number` + - `description: optional string` - The sampling temperature used for this run. If not set, defaults to 1. + The description of the tool. - - `top_p: optional number` + - `type: "mcp_list_tools"` - The nucleus sampling value used for this run. If not set, defaults to 1. + The type of the item. Always `mcp_list_tools`. -### Example + - `"mcp_list_tools"` -```http -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" \ - -d '{ - "assistant_id": "assistant_id", - "temperature": 1, - "top_p": 1 - }' -``` + - `agent: optional object { agent_name }` -#### Response + The agent that produced this item. -```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 -} -``` + - `agent_name: string` -### Example + The canonical name of the agent that produced this item. -```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" - }' -``` + - `error: optional string` -#### Response + Error message if the server could not list tools. -```json -{ - "id": "run_abc123", - "object": "thread.run", - "created_at": 1699063290, - "assistant_id": "asst_abc123", - "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": [ - { - "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 -} -``` + - `McpApprovalRequest object { id, arguments, name, 3 more }` -### 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 - }' -``` + A request for human approval of a tool invocation. -#### Response + - `id: string` -```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}} + The unique ID of the approval request. -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}} + - `arguments: string` -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}} + A JSON string of arguments for the tool. -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} + - `name: string` -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} + The name of the tool to run. -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":{}} + - `server_label: string` -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":{}} + The label of the MCP server making the request. -event: thread.message.delta -data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"Hello","annotations":[]}}]}} + - `type: "mcp_approval_request"` -... + The type of the item. Always `mcp_approval_request`. -event: thread.message.delta -data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" today"}}]}} + - `"mcp_approval_request"` -event: thread.message.delta -data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"?"}}]}} + - `agent: optional object { agent_name }` -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 agent that produced this item. -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}} + - `agent_name: string` -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}} + The canonical name of the agent that produced this item. -event: done -data: [DONE] -``` + - `McpApprovalResponse object { approval_request_id, approve, type, 3 more }` -### Streaming with Functions + A response to an MCP approval request. -```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 - }' -``` + - `approval_request_id: string` -#### Response + The ID of the approval request being answered. -```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}} + - `approve: boolean` -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}} + Whether the request was approved. -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: "mcp_approval_response"` -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} + The type of the item. Always `mcp_approval_response`. -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} + - `"mcp_approval_response"` -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":{}} + - `id: optional string` -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":{}} + The unique ID of the approval response -event: thread.message.delta -data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"Hello","annotations":[]}}]}} + - `agent: optional object { agent_name }` -... + The agent that produced this item. -event: thread.message.delta -data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" today"}}]}} + - `agent_name: string` -event: thread.message.delta -data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"?"}}]}} + The canonical name of the agent that produced this item. -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":{}} + - `reason: optional string` -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}} + Optional reason for the decision. -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}} + - `McpCall object { id, arguments, name, 7 more }` -event: done -data: [DONE] -``` + An invocation of a tool on an MCP server. -## Retrieve run + - `id: string` -**get** `/threads/{thread_id}/runs/{run_id}` + The unique ID of the tool call. -Retrieve run + - `arguments: string` -### Path Parameters + A JSON string of the arguments passed to the tool. -- `thread_id: string` + - `name: string` -- `run_id: string` + The name of the tool that was run. -### Returns + - `server_label: string` -- `Run object { id, assistant_id, cancelled_at, 24 more }` + The label of the MCP server running the tool. - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `type: "mcp_call"` - - `id: string` + The type of the item. Always `mcp_call`. - The identifier, which can be referenced in API endpoints. + - `"mcp_call"` - - `assistant_id: string` + - `agent: optional object { agent_name }` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + The agent that produced this item. - - `cancelled_at: number` + - `agent_name: string` - The Unix timestamp (in seconds) for when the run was cancelled. + The canonical name of the agent that produced this item. - - `completed_at: number` + - `approval_request_id: optional string` - The Unix timestamp (in seconds) for when the run was completed. + 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. - - `created_at: number` + - `error: optional string` - The Unix timestamp (in seconds) for when the run was created. + The error from the tool call, if any. - - `expires_at: number` + - `output: optional string` - The Unix timestamp (in seconds) for when the run will expire. + The output from the tool call. - - `failed_at: number` + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - The Unix timestamp (in seconds) for when the run failed. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `incomplete_details: object { reason }` + - `"in_progress"` - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + - `"completed"` - - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` + - `"incomplete"` - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + - `"calling"` - - `"max_completion_tokens"` + - `"failed"` - - `"max_prompt_tokens"` + - `CustomToolCallOutput object { call_id, output, type, 3 more }` - - `instructions: string` + The output of a custom tool call from your code, being sent back to the model. - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `call_id: string` - - `last_error: object { code, message }` + The call ID, used to map this custom tool call output to a custom tool call. - The last error associated with this run. Will be `null` if there are no errors. + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + - `StringOutput = string` - - `"server_error"` + A string of the output of the custom tool call. - - `"rate_limit_exceeded"` + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `"invalid_prompt"` + Text, image, or file output of the custom tool call. - - `message: string` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - A human-readable description of the error. + A text input to the model. - - `max_completion_tokens: number` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - The maximum number of completion tokens specified to have been used over the course of the run. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `max_prompt_tokens: number` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - The maximum number of prompt tokens specified to have been used over the course of the run. + A file input to the model. - - `metadata: Metadata` + - `type: "custom_tool_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 type of the custom tool call output. Always `custom_tool_call_output`. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `"custom_tool_call_output"` - - `model: string` + - `id: optional string` - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + The unique ID of the custom tool call output in the OpenAI platform. - - `object: "thread.run"` + - `agent: optional object { agent_name }` - The object type, which is always `thread.run`. + The agent that produced this item. - - `"thread.run"` + - `agent_name: string` - - `parallel_tool_calls: boolean` + The canonical name of the agent that produced this item. - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `caller: optional object { type } or object { caller_id, type }` - - `required_action: object { submit_tool_outputs, type }` + The execution context that produced this tool call. - Details on the action required to continue the run. Will be `null` if no action is required. + - `Direct object { type }` - - `submit_tool_outputs: object { tool_calls }` + - `type: "direct"` - Details on the tool outputs needed for this run to continue. + The caller type. Always `direct`. - - `tool_calls: array of RequiredActionFunctionToolCall` + - `"direct"` - A list of the relevant tool calls. + - `Program object { caller_id, type }` - - `id: string` + - `caller_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](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. + The call ID of the program item that produced this tool call. - - `function: object { arguments, name }` + - `type: "program"` - The function definition. + The caller type. Always `program`. - - `arguments: string` + - `"program"` - The arguments that the model expects you to pass to the function. + - `CustomToolCall object { call_id, input, name, 5 more }` - - `name: string` + A call to a custom tool created by the model. - The name of the function. + - `call_id: string` - - `type: "function"` + An identifier used to map this custom tool call to a tool call output. - The type of tool call the output is required for. For now, this is always `function`. + - `input: string` - - `"function"` + The input for the custom tool call generated by the model. - - `type: "submit_tool_outputs"` + - `name: string` - For now, this is always `submit_tool_outputs`. + The name of the custom tool being called. - - `"submit_tool_outputs"` + - `type: "custom_tool_call"` - - `response_format: AssistantResponseFormatOption` + The type of the custom tool call. Always `custom_tool_call`. - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `"custom_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](https://platform.openai.com/docs/guides/structured-outputs). + - `id: optional string` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + The unique ID of the custom tool call in the OpenAI platform. - **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: optional object { agent_name }` - - `"auto"` + The agent that produced this item. - `auto` is the default value + - `agent_name: string` - - `"auto"` + The canonical name of the agent that produced this item. - - `ResponseFormatText object { type }` + - `caller: optional object { type } or object { caller_id, type }` - Default response format. Used to generate text responses. + The execution context that produced this tool call. - - `type: "text"` + - `Direct object { type }` - The type of response format being defined. Always `text`. + - `type: "direct"` - - `"text"` + - `"direct"` - - `ResponseFormatJSONObject object { type }` + - `Program object { caller_id, 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. + - `caller_id: string` - - `type: "json_object"` + The call ID of the program item that produced this tool call. - The type of response format being defined. Always `json_object`. + - `type: "program"` - - `"json_object"` + - `"program"` - - `ResponseFormatJSONSchema object { json_schema, type }` + - `namespace: optional string` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + The namespace of the custom tool being called. - - `json_schema: object { name, description, schema, strict }` + - `CompactionTrigger object { type, agent }` - Structured Outputs configuration options, including a JSON Schema. + Compacts the current context. Must be the final input item. - - `name: string` + - `type: "compaction_trigger"` - 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 item. Always `compaction_trigger`. - - `description: optional string` + - `"compaction_trigger"` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `agent: optional object { agent_name }` - - `schema: optional map[unknown]` + The agent that produced this item. - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `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](https://platform.openai.com/docs/guides/structured-outputs). + - `ItemReference object { id, agent, type }` - - `type: "json_schema"` + An internal identifier for an item to reference. - The type of response format being defined. Always `json_schema`. + - `id: string` - - `"json_schema"` + The ID of the item to reference. - - `started_at: number` + - `agent: optional object { agent_name }` - The Unix timestamp (in seconds) for when the run was started. + The agent that produced this item. - - `status: RunStatus` + - `agent_name: string` - The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. + The canonical name of the agent that produced this item. - - `"queued"` + - `type: optional "item_reference"` - - `"in_progress"` + The type of item to reference. Always `item_reference`. - - `"requires_action"` + - `"item_reference"` - - `"cancelling"` + - `Program object { id, call_id, code, 3 more }` - - `"cancelled"` + - `id: string` - - `"failed"` + The unique ID of this program item. - - `"completed"` + - `call_id: string` - - `"incomplete"` + The stable call ID of the program item. - - `"expired"` + - `code: string` - - `thread_id: string` + The JavaScript source executed by programmatic tool calling. - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + - `fingerprint: string` - - `tool_choice: AssistantToolChoiceOption` + Opaque program replay fingerprint that must be round-tripped. - 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. + - `type: "program"` - - `Auto = "none" or "auto" or "required"` + The item type. Always `program`. - `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. + - `"program"` - - `"none"` + - `agent: optional object { agent_name }` - - `"auto"` + The agent that produced this item. - - `"required"` + - `agent_name: string` - - `AssistantToolChoice object { type, function }` + The canonical name of the agent that produced this item. - Specifies a tool the model should use. Use to force the model to call a specific tool. + - `ProgramOutput object { id, call_id, result, 3 more }` - - `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 unique ID of this program output item. - - `"function"` + - `call_id: string` - - `"code_interpreter"` + The call ID of the program item. - - `"file_search"` + - `result: string` - - `function: optional AssistantToolChoiceFunction` + The result produced by the program item. - - `name: string` + - `status: "completed" or "incomplete"` - The name of the function to call. + The terminal status of the program output. - - `tools: array of AssistantTool` + - `"completed"` - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `"incomplete"` - - `CodeInterpreterTool object { type }` + - `type: "program_output"` - - `type: "code_interpreter"` + The item type. Always `program_output`. - The type of tool being defined: `code_interpreter` + - `"program_output"` - - `"code_interpreter"` + - `agent: optional object { agent_name }` - - `FileSearchTool object { type, file_search }` + The agent that produced this item. - - `type: "file_search"` + - `agent_name: string` - The type of tool being defined: `file_search` + The canonical name of the agent that produced this item. - - `"file_search"` + - `metadata: map[string]` - - `file_search: optional object { max_num_results, ranking_options }` + 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. - Overrides for the file search tool. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `max_num_results: optional number` + - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or 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. + 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. - Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `"gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more` - - `ranking_options: optional object { score_threshold, ranker }` + 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 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-5.6-sol"` - See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `"gpt-5.6-terra"` - - `score_threshold: number` + - `"gpt-5.6-luna"` - The score threshold for the file search. All values must be a floating point number between 0 and 1. + - `"gpt-5.4"` - - `ranker: optional "auto" or "default_2024_08_21"` + - `"gpt-5.4-mini"` - The ranker to use for the file search. If not specified will use the `auto` ranker. + - `"gpt-5.4-nano"` - - `"auto"` + - `"gpt-5.4-mini-2026-03-17"` - - `"default_2024_08_21"` + - `"gpt-5.4-nano-2026-03-17"` - - `FunctionTool object { function, type }` + - `"gpt-5.3-chat-latest"` - - `function: FunctionDefinition` + - `"gpt-5.2"` - - `name: string` + - `"gpt-5.2-2025-12-11"` - 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-5.2-chat-latest"` - - `description: optional string` + - `"gpt-5.2-pro"` - A description of what the function does, used by the model to choose when and how to call the function. + - `"gpt-5.2-pro-2025-12-11"` - - `parameters: optional FunctionParameters` + - `"gpt-5.1"` - The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + - `"gpt-5.1-2025-11-13"` - Omitting `parameters` defines a function with an empty parameter list. + - `"gpt-5.1-codex"` - - `strict: optional boolean` + - `"gpt-5.1-mini"` - 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](https://platform.openai.com/docs/guides/function-calling). + - `"gpt-5.1-chat-latest"` - - `type: "function"` + - `"gpt-5"` - The type of tool being defined: `function` + - `"gpt-5-mini"` - - `"function"` + - `"gpt-5-nano"` - - `truncation_strategy: object { type, last_messages }` + - `"gpt-5-2025-08-07"` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `"gpt-5-mini-2025-08-07"` - - `type: "auto" or "last_messages"` + - `"gpt-5-nano-2025-08-07"` - 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-chat-latest"` - - `"auto"` + - `"gpt-4.1"` - - `"last_messages"` + - `"gpt-4.1-mini"` - - `last_messages: optional number` + - `"gpt-4.1-nano"` - The number of most recent messages from the thread when constructing the context for the run. + - `"gpt-4.1-2025-04-14"` - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + - `"gpt-4.1-mini-2025-04-14"` - 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.). + - `"gpt-4.1-nano-2025-04-14"` - - `completion_tokens: number` + - `"o4-mini"` - Number of completion tokens used over the course of the run. + - `"o4-mini-2025-04-16"` - - `prompt_tokens: number` + - `"o3"` - Number of prompt tokens used over the course of the run. + - `"o3-2025-04-16"` - - `total_tokens: number` + - `"o3-mini"` - Total number of tokens used (prompt + completion). + - `"o3-mini-2025-01-31"` - - `temperature: optional number` + - `"o1"` - The sampling temperature used for this run. If not set, defaults to 1. + - `"o1-2024-12-17"` - - `top_p: optional number` + - `"o1-preview"` - The nucleus sampling value used for this run. If not set, defaults to 1. + - `"o1-preview-2024-09-12"` -### Example + - `"o1-mini"` -```http -curl https://api.openai.com/v1/threads/$THREAD_ID/runs/$RUN_ID \ - -H 'OpenAI-Beta: assistants=v2' \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + - `"o1-mini-2024-09-12"` -#### Response + - `"gpt-4o"` -```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 -} -``` + - `"gpt-4o-2024-11-20"` -### Example + - `"gpt-4o-2024-08-06"` -```http -curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123 \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "OpenAI-Beta: assistants=v2" -``` + - `"gpt-4o-2024-05-13"` -#### Response + - `"gpt-4o-audio-preview"` -```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 -} -``` + - `"gpt-4o-audio-preview-2024-10-01"` -## Modify run + - `"gpt-4o-audio-preview-2024-12-17"` -**post** `/threads/{thread_id}/runs/{run_id}` + - `"gpt-4o-audio-preview-2025-06-03"` -Modify run + - `"gpt-4o-mini-audio-preview"` -### Path Parameters + - `"gpt-4o-mini-audio-preview-2024-12-17"` -- `thread_id: string` + - `"gpt-4o-search-preview"` -- `run_id: string` + - `"gpt-4o-mini-search-preview"` -### Body Parameters + - `"gpt-4o-search-preview-2025-03-11"` -- `metadata: optional Metadata` + - `"gpt-4o-mini-search-preview-2025-03-11"` - 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. + - `"chatgpt-4o-latest"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `"codex-mini-latest"` -### Returns + - `"gpt-4o-mini"` -- `Run object { id, assistant_id, cancelled_at, 24 more }` + - `"gpt-4o-mini-2024-07-18"` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `"gpt-4-turbo"` - - `id: string` + - `"gpt-4-turbo-2024-04-09"` - The identifier, which can be referenced in API endpoints. + - `"gpt-4-0125-preview"` - - `assistant_id: string` + - `"gpt-4-turbo-preview"` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + - `"gpt-4-1106-preview"` - - `cancelled_at: number` + - `"gpt-4-vision-preview"` - The Unix timestamp (in seconds) for when the run was cancelled. + - `"gpt-4"` - - `completed_at: number` + - `"gpt-4-0314"` - The Unix timestamp (in seconds) for when the run was completed. + - `"gpt-4-0613"` - - `created_at: number` + - `"gpt-4-32k"` - The Unix timestamp (in seconds) for when the run was created. + - `"gpt-4-32k-0314"` - - `expires_at: number` + - `"gpt-4-32k-0613"` - The Unix timestamp (in seconds) for when the run will expire. + - `"gpt-3.5-turbo"` - - `failed_at: number` + - `"gpt-3.5-turbo-16k"` - The Unix timestamp (in seconds) for when the run failed. + - `"gpt-3.5-turbo-0301"` - - `incomplete_details: object { reason }` + - `"gpt-3.5-turbo-0613"` - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + - `"gpt-3.5-turbo-1106"` - - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` + - `"gpt-3.5-turbo-0125"` - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + - `"gpt-3.5-turbo-16k-0613"` - - `"max_completion_tokens"` + - `"o1-pro"` - - `"max_prompt_tokens"` + - `"o1-pro-2025-03-19"` - - `instructions: string` + - `"o3-pro"` - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `"o3-pro-2025-06-10"` - - `last_error: object { code, message }` + - `"o3-deep-research"` - The last error associated with this run. Will be `null` if there are no errors. + - `"o3-deep-research-2025-06-26"` - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` + - `"o4-mini-deep-research"` - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + - `"o4-mini-deep-research-2025-06-26"` - - `"server_error"` + - `"computer-use-preview"` - - `"rate_limit_exceeded"` + - `"computer-use-preview-2025-03-11"` - - `"invalid_prompt"` + - `"gpt-5-codex"` - - `message: string` + - `"gpt-5-pro"` - A human-readable description of the error. + - `"gpt-5-pro-2025-10-06"` - - `max_completion_tokens: number` + - `"gpt-5.1-codex-max"` - The maximum number of completion tokens specified to have been used over the course of the run. + - `string` - - `max_prompt_tokens: number` + - `object: "response"` - The maximum number of prompt tokens specified to have been used over the course of the run. + The object type of this resource - always set to `response`. - - `metadata: Metadata` + - `"response"` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `output: array of BetaResponseOutputItem` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + An array of content items generated by the model. - - `model: 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 model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `BetaResponseOutputMessage object { id, content, role, 4 more }` - - `object: "thread.run"` + An output message from the model. - The object type, which is always `thread.run`. + - `FileSearchCall object { id, queries, status, 3 more }` - - `"thread.run"` + The results of a file search tool call. See the + [file search guide](/docs/guides/tools-file-search) for more information. - - `parallel_tool_calls: boolean` + - `id: string` - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + The unique ID of the file search tool call. - - `required_action: object { submit_tool_outputs, type }` + - `queries: array of string` - Details on the action required to continue the run. Will be `null` if no action is required. + The queries used to search for files. - - `submit_tool_outputs: object { tool_calls }` + - `status: "in_progress" or "searching" or "completed" or 2 more` - Details on the tool outputs needed for this run to continue. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `tool_calls: array of RequiredActionFunctionToolCall` + - `"in_progress"` - A list of the relevant tool calls. + - `"searching"` - - `id: string` + - `"completed"` - 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](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. + - `"incomplete"` - - `function: object { arguments, name }` + - `"failed"` - The function definition. + - `type: "file_search_call"` - - `arguments: string` + The type of the file search tool call. Always `file_search_call`. - The arguments that the model expects you to pass to the function. + - `"file_search_call"` - - `name: string` + - `agent: optional object { agent_name }` - The name of the function. + The agent that produced this item. - - `type: "function"` + - `agent_name: string` - The type of tool call the output is required for. For now, this is always `function`. + The canonical name of the agent that produced this item. - - `"function"` + - `results: optional array of object { attributes, file_id, filename, 2 more }` - - `type: "submit_tool_outputs"` + The results of the file search tool call. - For now, this is always `submit_tool_outputs`. + - `attributes: optional map[string or number or boolean]` - - `"submit_tool_outputs"` + 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_format: AssistantResponseFormatOption` + - `string` - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/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](https://platform.openai.com/docs/guides/structured-outputs). + - `boolean` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `file_id: optional 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 unique ID of the file. - - `"auto"` + - `filename: optional string` - `auto` is the default value + The name of the file. - - `"auto"` + - `score: optional number` - - `ResponseFormatText object { type }` + The relevance score of the file - a value between 0 and 1. - Default response format. Used to generate text responses. + - `text: optional string` - - `type: "text"` + The text that was retrieved from the file. - The type of response format being defined. Always `text`. + - `FunctionCall object { arguments, call_id, name, 6 more }` - - `"text"` + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. - - `ResponseFormatJSONObject object { type }` + - `arguments: 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. + A JSON string of the arguments to pass to the function. - - `type: "json_object"` + - `call_id: string` - The type of response format being defined. Always `json_object`. + The unique ID of the function tool call generated by the model. - - `"json_object"` + - `name: string` - - `ResponseFormatJSONSchema object { json_schema, type }` + The name of the function to run. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `type: "function_call"` - - `json_schema: object { name, description, schema, strict }` + The type of the function tool call. Always `function_call`. - Structured Outputs configuration options, including a JSON Schema. + - `"function_call"` - - `name: string` + - `id: 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 unique ID of the function tool call. - - `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. - - `schema: optional map[unknown]` + - `agent_name: 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 canonical name of the agent that produced this item. - - `strict: optional boolean` + - `caller: optional object { type } or object { caller_id, type }` - 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](https://platform.openai.com/docs/guides/structured-outputs). + The execution context that produced this tool call. - - `type: "json_schema"` + - `Direct object { type }` - The type of response format being defined. Always `json_schema`. + - `type: "direct"` - - `"json_schema"` + - `"direct"` - - `started_at: number` + - `Program object { caller_id, type }` - The Unix timestamp (in seconds) for when the run was started. + - `caller_id: string` - - `status: RunStatus` + The call ID of the program item that produced this tool call. - The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. + - `type: "program"` - - `"queued"` + - `"program"` - - `"in_progress"` + - `namespace: optional string` - - `"requires_action"` + The namespace of the function to run. - - `"cancelling"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"cancelled"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"failed"` + - `"in_progress"` - `"completed"` - `"incomplete"` - - `"expired"` + - `FunctionCallOutput object { id, call_id, output, 5 more }` - - `thread_id: string` + - `id: string` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + The unique ID of the function call tool output. - - `tool_choice: AssistantToolChoiceOption` + - `call_id: 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. + The unique ID of the function tool call generated by the model. - - `Auto = "none" or "auto" or "required"` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - `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 output from the function call generated by your code. + Can be a string or an list of output content. - - `"none"` + - `StringOutput = string` - - `"auto"` + A string of the output of the function call. - - `"required"` + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `AssistantToolChoice object { type, function }` + Text, image, or file output of the function call. - Specifies a tool the model should use. Use to force the model to call a specific tool. + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `type: "function" or "code_interpreter" or "file_search"` + A text input to the model. - The type of the tool. If type is `function`, the function name must be set + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `"function"` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `"code_interpreter"` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `"file_search"` + A file input to the model. - - `function: optional AssistantToolChoiceFunction` + - `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 function to call. + - `"in_progress"` - - `tools: array of AssistantTool` + - `"completed"` - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `"incomplete"` - - `CodeInterpreterTool object { type }` + - `type: "function_call_output"` - - `type: "code_interpreter"` + The type of the function tool call output. Always `function_call_output`. - The type of tool being defined: `code_interpreter` + - `"function_call_output"` - - `"code_interpreter"` + - `agent: optional object { agent_name }` - - `FileSearchTool object { type, file_search }` + The agent that produced this item. - - `type: "file_search"` + - `agent_name: string` - The type of tool being defined: `file_search` + The canonical name of the agent that produced this item. - - `"file_search"` + - `caller: optional object { type } or object { caller_id, type }` - - `file_search: optional object { max_num_results, ranking_options }` + The execution context that produced this tool call. - Overrides for the file search tool. + - `Direct object { type }` - - `max_num_results: optional number` + - `type: "direct"` - 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 caller type. Always `direct`. - Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `"direct"` - - `ranking_options: optional object { score_threshold, ranker }` + - `Program object { caller_id, 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. + - `caller_id: string` - See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + 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`. - - `ranker: optional "auto" or "default_2024_08_21"` + - `"program"` - The ranker to use for the file search. If not specified will use the `auto` ranker. + - `created_by: optional string` - - `"auto"` + The identifier of the actor that created the item. - - `"default_2024_08_21"` + - `AgentMessage object { id, author, content, 3 more }` - - `FunctionTool object { function, type }` + - `id: string` - - `function: FunctionDefinition` + The unique ID of the agent message. - - `name: string` + - `author: 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 sending agent identity. - - `description: optional string` - - A description of what the function does, used by the model to choose when and how to call the function. + - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` - - `parameters: optional FunctionParameters` + Encrypted content sent between agents. - The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - Omitting `parameters` defines a function with an empty parameter list. + A text input to the model. - - `strict: optional boolean` + - `BetaResponseOutputText object { annotations, logprobs, text, 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](https://platform.openai.com/docs/guides/function-calling). + A text output from the model. - - `type: "function"` + - `Text object { text, type }` - The type of tool being defined: `function` + A text content. - - `"function"` + - `text: string` - - `truncation_strategy: object { type, last_messages }` + - `type: "text"` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `"text"` - - `type: "auto" or "last_messages"` + - `SummaryText object { text, type }` - 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`. + A summary text from the model. - - `"auto"` + - `text: string` - - `"last_messages"` + A summary of the reasoning output from the model so far. - - `last_messages: optional number` + - `type: "summary_text"` - The number of most recent messages from the thread when constructing the context for the run. + The type of the object. Always `summary_text`. - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + - `"summary_text"` - 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.). + - `ReasoningText object { text, type }` - - `completion_tokens: number` + Reasoning text from the model. - Number of completion tokens used over the course of the run. + - `text: string` - - `prompt_tokens: number` + The reasoning text from the model. - Number of prompt tokens used over the course of the run. + - `type: "reasoning_text"` - - `total_tokens: number` + The type of the reasoning text. Always `reasoning_text`. - Total number of tokens used (prompt + completion). + - `"reasoning_text"` - - `temperature: optional number` + - `BetaResponseOutputRefusal object { refusal, type }` - The sampling temperature used for this run. If not set, defaults to 1. + A refusal from the model. - - `top_p: optional number` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - The nucleus sampling value used for this run. If not set, defaults to 1. + An image input to the model. Learn about [image inputs](/docs/guides/vision). -### Example + - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` -```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 '{}' -``` + A screenshot of a computer. -#### Response + - `detail: "low" or "high" or "auto" or "original"` -```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 detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. -### Example + - `"low"` -```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" - } - }' -``` + - `"high"` -#### Response + - `"auto"` -```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 -} -``` + - `"original"` -## Submit tool outputs to run + - `file_id: string` -**post** `/threads/{thread_id}/runs/{run_id}/submit_tool_outputs` + The identifier of an uploaded file that contains the screenshot. -Submit tool outputs to run + - `image_url: string` -### Path Parameters + The URL of the screenshot image. -- `thread_id: string` + - `type: "computer_screenshot"` -- `run_id: string` + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. -### Body Parameters + - `"computer_screenshot"` -- `tool_outputs: array of object { output, tool_call_id }` + - `prompt_cache_breakpoint: optional object { mode }` - A list of tools for which the outputs are being submitted. + Marks the exact end of a reusable 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 of the tool call to be submitted to continue the run. + The breakpoint mode. Always `explicit`. - - `tool_call_id: optional string` + - `"explicit"` - The ID of the tool call in the `required_action` object within the run object the output is being submitted for. + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` -- `stream: optional boolean` + A file input to the model. - 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. + - `EncryptedContent object { encrypted_content, type }` -### Returns + Opaque encrypted content that Responses API decrypts inside trusted model execution. -- `Run object { id, assistant_id, cancelled_at, 24 more }` + - `encrypted_content: string` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + Opaque encrypted content. - - `id: string` + - `type: "encrypted_content"` - The identifier, which can be referenced in API endpoints. + The type of the input item. Always `encrypted_content`. - - `assistant_id: string` + - `"encrypted_content"` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + - `recipient: string` - - `cancelled_at: number` + The destination agent identity. - The Unix timestamp (in seconds) for when the run was cancelled. + - `type: "agent_message"` - - `completed_at: number` + The type of the item. Always `agent_message`. - The Unix timestamp (in seconds) for when the run was completed. + - `"agent_message"` - - `created_at: number` + - `agent: optional object { agent_name }` - The Unix timestamp (in seconds) for when the run was created. + The agent that produced this item. - - `expires_at: number` + - `agent_name: string` - The Unix timestamp (in seconds) for when the run will expire. + The canonical name of the agent that produced this item. - - `failed_at: number` + - `MultiAgentCall object { id, action, arguments, 3 more }` - The Unix timestamp (in seconds) for when the run failed. + - `id: string` - - `incomplete_details: object { reason }` + The unique ID of the multi-agent call item. - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` + The multi-agent action to execute. - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + - `"spawn_agent"` - - `"max_completion_tokens"` + - `"interrupt_agent"` - - `"max_prompt_tokens"` + - `"list_agents"` - - `instructions: string` + - `"send_message"` - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `"followup_task"` - - `last_error: object { code, message }` + - `"wait_agent"` - The last error associated with this run. Will be `null` if there are no errors. + - `arguments: string` - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` + The JSON string of arguments generated for the action. - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + - `call_id: string` - - `"server_error"` + The unique ID linking this call to its output. - - `"rate_limit_exceeded"` + - `type: "multi_agent_call"` - - `"invalid_prompt"` + The type of the multi-agent call. Always `multi_agent_call`. - - `message: string` + - `"multi_agent_call"` - A human-readable description of the error. + - `agent: optional object { agent_name }` - - `max_completion_tokens: number` + The agent that produced this item. - The maximum number of completion tokens specified to have been used over the course of the run. + - `agent_name: string` - - `max_prompt_tokens: number` + The canonical name of the agent that produced this item. - The maximum number of prompt tokens specified to have been used over the course of the run. + - `MultiAgentCallOutput object { id, action, call_id, 3 more }` - - `metadata: Metadata` + - `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 ID of the multi-agent call output item. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `model: string` + The multi-agent action that produced this result. - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `"spawn_agent"` - - `object: "thread.run"` + - `"interrupt_agent"` - The object type, which is always `thread.run`. + - `"list_agents"` - - `"thread.run"` + - `"send_message"` - - `parallel_tool_calls: boolean` + - `"followup_task"` - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `"wait_agent"` - - `required_action: object { submit_tool_outputs, type }` + - `call_id: string` - Details on the action required to continue the run. Will be `null` if no action is required. + The unique ID of the multi-agent call. - - `submit_tool_outputs: object { tool_calls }` + - `output: array of BetaResponseOutputText` - Details on the tool outputs needed for this run to continue. + Text output returned by the multi-agent action. - - `tool_calls: array of RequiredActionFunctionToolCall` + - `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 list of the relevant tool calls. + The annotations of the text output. - - `id: string` + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - 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](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. + - `text: string` - - `function: object { arguments, name }` + The text output from the model. - The function definition. + - `type: "output_text"` - - `arguments: string` + The type of the output text. Always `output_text`. - The arguments that the model expects you to pass to the function. + - `type: "multi_agent_call_output"` - - `name: string` + The type of the multi-agent result. Always `multi_agent_call_output`. - The name of the function. + - `"multi_agent_call_output"` - - `type: "function"` + - `agent: optional object { agent_name }` - The type of tool call the output is required for. For now, this is always `function`. + The agent that produced this item. - - `"function"` + - `agent_name: string` - - `type: "submit_tool_outputs"` + The canonical name of the agent that produced this item. - For now, this is always `submit_tool_outputs`. + - `WebSearchCall object { id, action, status, 2 more }` - - `"submit_tool_outputs"` + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. - - `response_format: AssistantResponseFormatOption` + - `id: string` - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/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 web 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](https://platform.openai.com/docs/guides/structured-outputs). + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + 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). - **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. + - `Search object { type, queries, query, sources }` - - `"auto"` + Action type "search" - Performs a web search query. - `auto` is the default value + - `type: "search"` - - `"auto"` + The action type. - - `ResponseFormatText object { type }` + - `"search"` - Default response format. Used to generate text responses. + - `queries: optional array of string` - - `type: "text"` + The search queries. - The type of response format being defined. Always `text`. + - `query: optional string` - - `"text"` + The search query. - - `ResponseFormatJSONObject object { type }` + - `sources: optional array of object { type, 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. + The sources used in the search. - - `type: "json_object"` + - `type: "url"` - The type of response format being defined. Always `json_object`. + The type of source. Always `url`. - - `"json_object"` + - `"url"` - - `ResponseFormatJSONSchema object { json_schema, type }` + - `url: string` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + The URL of the source. - - `json_schema: object { name, description, schema, strict }` + - `OpenPage object { type, url }` - Structured Outputs configuration options, including a JSON Schema. + Action type "open_page" - Opens a specific URL from search results. - - `name: string` + - `type: "open_page"` - 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 action type. - - `description: optional string` + - `"open_page"` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `url: optional string` - - `schema: optional map[unknown]` + The URL opened 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/). + - `FindInPage object { pattern, type, url }` - - `strict: optional boolean` + Action type "find_in_page": Searches for a pattern within a loaded page. - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + - `pattern: string` - - `type: "json_schema"` + The pattern or text to search for within the page. - The type of response format being defined. Always `json_schema`. + - `type: "find_in_page"` - - `"json_schema"` + The action type. - - `started_at: number` + - `"find_in_page"` - The Unix timestamp (in seconds) for when the run was started. + - `url: string` - - `status: RunStatus` + The URL of the page searched for the pattern. - The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. + - `status: "in_progress" or "searching" or "completed" or "failed"` - - `"queued"` + The status of the web search tool call. - `"in_progress"` - - `"requires_action"` - - - `"cancelling"` + - `"searching"` - - `"cancelled"` + - `"completed"` - `"failed"` - - `"completed"` - - - `"incomplete"` + - `type: "web_search_call"` - - `"expired"` + The type of the web search tool call. Always `web_search_call`. - - `thread_id: string` + - `"web_search_call"` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + - `agent: optional object { agent_name }` - - `tool_choice: AssistantToolChoiceOption` + The agent that produced this item. - 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. + - `agent_name: string` - - `Auto = "none" or "auto" or "required"` + The canonical name of the agent that produced this item. - `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. + - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` - - `"none"` + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - - `"auto"` + - `id: string` - - `"required"` + The unique ID of the computer call. - - `AssistantToolChoice object { type, function }` + - `call_id: string` - Specifies a tool the model should use. Use to force the model to call a specific tool. + An identifier used when responding to the tool call with output. - - `type: "function" or "code_interpreter" or "file_search"` + - `pending_safety_checks: array of object { id, code, message }` - The type of the tool. If type is `function`, the function name must be set + The pending safety checks for the computer call. - - `"function"` + - `id: string` - - `"code_interpreter"` + The ID of the pending safety check. - - `"file_search"` + - `code: optional string` - - `function: optional AssistantToolChoiceFunction` + The type of the pending safety check. - - `name: string` + - `message: optional string` - The name of the function to call. + Details about the pending safety check. - - `tools: array of AssistantTool` + - `status: "in_progress" or "completed" or "incomplete"` - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `CodeInterpreterTool object { type }` + - `"in_progress"` - - `type: "code_interpreter"` + - `"completed"` - The type of tool being defined: `code_interpreter` + - `"incomplete"` - - `"code_interpreter"` + - `type: "computer_call"` - - `FileSearchTool object { type, file_search }` + The type of the computer call. Always `computer_call`. - - `type: "file_search"` + - `"computer_call"` - The type of tool being defined: `file_search` + - `action: optional BetaComputerAction` - - `"file_search"` + A click action. - - `file_search: optional object { max_num_results, ranking_options }` + - `actions: optional BetaComputerActionList` - Overrides for the file search tool. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `max_num_results: optional number` + - `agent: optional object { agent_name }` - 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 agent that produced this item. - Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `agent_name: string` - - `ranking_options: optional object { score_threshold, ranker }` + The canonical name of the agent that produced this item. - 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. + - `ComputerCallOutput object { id, call_id, output, 5 more }` - See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `id: string` - - `score_threshold: number` + The unique ID of the computer call tool output. - The score threshold for the file search. All values must be a floating point number between 0 and 1. + - `call_id: string` - - `ranker: optional "auto" or "default_2024_08_21"` + The ID of the computer tool call that produced the output. - The ranker to use for the file search. If not specified will use the `auto` ranker. + - `output: BetaResponseComputerToolCallOutputScreenshot` - - `"auto"` + A computer screenshot image used with the computer use tool. - - `"default_2024_08_21"` + - `status: "completed" or "incomplete" or "failed" or "in_progress"` - - `FunctionTool object { function, type }` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `function: FunctionDefinition` + - `"completed"` - - `name: string` + - `"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. + - `"failed"` - - `description: optional string` + - `"in_progress"` - A description of what the function does, used by the model to choose when and how to call the function. + - `type: "computer_call_output"` - - `parameters: optional FunctionParameters` + The type of the computer tool call output. Always `computer_call_output`. - The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + - `"computer_call_output"` - Omitting `parameters` defines a function with an empty parameter list. + - `acknowledged_safety_checks: optional array of object { id, code, message }` - - `strict: optional boolean` + The safety checks reported by the API that have been acknowledged by the + 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](https://platform.openai.com/docs/guides/function-calling). + - `id: string` - - `type: "function"` + The ID of the pending safety check. - The type of tool being defined: `function` + - `code: optional string` - - `"function"` + The type of the pending safety check. - - `truncation_strategy: object { type, last_messages }` + - `message: optional string` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + Details about the pending safety check. - - `type: "auto" or "last_messages"` + - `agent: optional object { agent_name }` - 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 agent that produced this item. - - `"auto"` + - `agent_name: string` - - `"last_messages"` + The canonical name of the agent that produced this item. - - `last_messages: optional number` + - `created_by: optional string` - The number of most recent messages from the thread when constructing the context for the run. + The identifier of the actor that created the item. - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + - `Reasoning object { id, summary, type, 4 more }` - 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.). + 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). - - `completion_tokens: number` + - `id: string` - Number of completion tokens used over the course of the run. + The unique identifier of the reasoning content. - - `prompt_tokens: number` + - `summary: array of object { text, type }` - Number of prompt tokens used over the course of the run. + Reasoning summary content. - - `total_tokens: number` + - `text: string` - Total number of tokens used (prompt + completion). + A summary of the reasoning output from the model so far. - - `temperature: optional number` + - `type: "summary_text"` - The sampling temperature used for this run. If not set, defaults to 1. + The type of the object. Always `summary_text`. - - `top_p: optional number` + - `"summary_text"` - The nucleus sampling value used for this run. If not set, defaults to 1. + - `type: "reasoning"` -### Example + The type of the object. Always `reasoning`. -```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": [ - {} - ] - }' -``` + - `"reasoning"` -#### Response + - `agent: optional object { agent_name }` -```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 agent that produced this item. -### Example + - `agent_name: 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 canonical name of the agent that produced this item. -#### Response + - `content: optional array of object { text, type }` -```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 -} -``` + Reasoning text content. -### Streaming + - `text: 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." - } - ], - "stream": true - }' -``` + The reasoning text from the model. -#### Response + - `type: "reasoning_text"` -```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}} + The type of the reasoning text. Always `reasoning_text`. -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}} + - `"reasoning_text"` -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}} + - `encrypted_content: optional string` -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 encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. -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} + - `status: optional "in_progress" or "completed" or "incomplete"` -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 status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. -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":{}} + - `"in_progress"` -event: thread.message.delta -data: {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"The","annotations":[]}}]}} + - `"completed"` -event: thread.message.delta -data: {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" current"}}]}} + - `"incomplete"` -event: thread.message.delta -data: {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" weather"}}]}} + - `Program object { id, call_id, code, 3 more }` -... + - `id: string` -event: thread.message.delta -data: {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" sunny"}}]}} + The unique ID of the program item. -event: thread.message.delta -data: {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"."}}]}} + - `call_id: 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 stable call ID of the program item. -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}} + - `code: 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 JavaScript source executed by programmatic tool calling. -event: done -data: [DONE] -``` + - `fingerprint: string` -## Cancel a run + Opaque program replay fingerprint that must be round-tripped. -**post** `/threads/{thread_id}/runs/{run_id}/cancel` + - `type: "program"` -Cancel a run + The type of the item. Always `program`. -### Path Parameters + - `"program"` -- `thread_id: string` + - `agent: optional object { agent_name }` -- `run_id: string` + The agent that produced this item. -### Returns + - `agent_name: string` -- `Run object { id, assistant_id, cancelled_at, 24 more }` + The canonical name of the agent that produced this item. - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `ProgramOutput object { id, call_id, result, 3 more }` - `id: string` - The identifier, which can be referenced in API endpoints. + The unique ID of the program output item. - - `assistant_id: string` + - `call_id: string` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + The call ID of the program item. - - `cancelled_at: number` + - `result: string` - The Unix timestamp (in seconds) for when the run was cancelled. + The result produced by the program item. - - `completed_at: number` + - `status: "completed" or "incomplete"` - The Unix timestamp (in seconds) for when the run was completed. + The terminal status of the program output item. - - `created_at: number` + - `"completed"` - The Unix timestamp (in seconds) for when the run was created. + - `"incomplete"` - - `expires_at: number` + - `type: "program_output"` - The Unix timestamp (in seconds) for when the run will expire. + The type of the item. Always `program_output`. - - `failed_at: number` + - `"program_output"` - The Unix timestamp (in seconds) for when the run failed. + - `agent: optional object { agent_name }` - - `incomplete_details: object { reason }` + The agent that produced this item. - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + - `agent_name: string` - - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` + The canonical name of the agent that produced this item. - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + - `ToolSearchCall object { id, arguments, call_id, 5 more }` - - `"max_completion_tokens"` + - `id: string` - - `"max_prompt_tokens"` + The unique ID of the tool search call item. - - `instructions: string` + - `arguments: unknown` - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + Arguments used for the tool search call. - - `last_error: object { code, message }` + - `call_id: string` - The last error associated with this run. Will be `null` if there are no errors. + The unique ID of the tool search call generated by the model. - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` + - `execution: "server" or "client"` - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + Whether tool search was executed by the server or by the client. - - `"server_error"` + - `"server"` - - `"rate_limit_exceeded"` + - `"client"` - - `"invalid_prompt"` + - `status: "in_progress" or "completed" or "incomplete"` - - `message: string` + The status of the tool search call item that was recorded. - A human-readable description of the error. + - `"in_progress"` - - `max_completion_tokens: number` + - `"completed"` - The maximum number of completion tokens specified to have been used over the course of the run. + - `"incomplete"` - - `max_prompt_tokens: number` + - `type: "tool_search_call"` - The maximum number of prompt tokens specified to have been used over the course of the run. + The type of the item. Always `tool_search_call`. - - `metadata: Metadata` + - `"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. + - `agent: optional object { agent_name }` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The agent that produced this item. - - `model: string` + - `agent_name: string` - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + The canonical name of the agent that produced this item. - - `object: "thread.run"` + - `created_by: optional string` - The object type, which is always `thread.run`. + The identifier of the actor that created the item. - - `"thread.run"` + - `ToolSearchOutput object { id, call_id, execution, 5 more }` - - `parallel_tool_calls: boolean` + - `id: string` - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + The unique ID of the tool search output item. - - `required_action: object { submit_tool_outputs, type }` + - `call_id: string` - Details on the action required to continue the run. Will be `null` if no action is required. + The unique ID of the tool search call generated by the model. - - `submit_tool_outputs: object { tool_calls }` + - `execution: "server" or "client"` - Details on the tool outputs needed for this run to continue. + Whether tool search was executed by the server or by the client. - - `tool_calls: array of RequiredActionFunctionToolCall` + - `"server"` - A list of the relevant tool calls. + - `"client"` - - `id: string` + - `status: "in_progress" or "completed" or "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](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. + The status of the tool search output item that was recorded. - - `function: object { arguments, name }` + - `"in_progress"` - The function definition. + - `"completed"` - - `arguments: string` + - `"incomplete"` - The arguments that the model expects you to pass to the function. + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - - `name: string` + The loaded tool definitions returned by tool search. - The name of the function. + - `Function object { name, parameters, strict, 5 more }` - - `type: "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). - The type of tool call the output is required for. For now, this is always `function`. + - `name: string` - - `"function"` + The name of the function to call. - - `type: "submit_tool_outputs"` + - `parameters: map[unknown]` - For now, this is always `submit_tool_outputs`. + A JSON schema object describing the parameters of the function. - - `"submit_tool_outputs"` + - `strict: boolean` - - `response_format: AssistantResponseFormatOption` + Whether strict parameter validation is enforced for this function tool. - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `type: "function"` - 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](https://platform.openai.com/docs/guides/structured-outputs). + The type of the function tool. Always `function`. - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `"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. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"auto"` + The tool invocation context(s). - `auto` is the default value + - `"direct"` - - `"auto"` + - `"programmatic"` - - `ResponseFormatText object { type }` + - `defer_loading: optional boolean` - Default response format. Used to generate text responses. + Whether this function is deferred and loaded via tool search. - - `type: "text"` + - `description: optional string` - The type of response format being defined. Always `text`. + A description of the function. Used by the model to determine whether or not to call the function. - - `"text"` + - `output_schema: optional map[unknown]` - - `ResponseFormatJSONObject object { type }` + A JSON schema object describing the JSON value encoded in string outputs for this function. - 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. + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - - `type: "json_object"` + 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 `json_object`. + - `type: "file_search"` - - `"json_object"` + The type of the file search tool. Always `file_search`. - - `ResponseFormatJSONSchema object { json_schema, type }` + - `"file_search"` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `vector_store_ids: array of string` - - `json_schema: object { name, description, schema, strict }` + The IDs of the vector stores to search. - Structured Outputs configuration options, including a JSON Schema. + - `filters: optional object { key, type, value } or object { filters, type }` - - `name: string` + A filter to apply. - 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. + - `ComparisonFilter object { key, type, value }` - - `description: optional string` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `key: string` - - `schema: optional map[unknown]` + The key to compare against the value. - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `type: "eq" or "ne" or "gt" or 5 more` - - `strict: optional boolean` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - 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](https://platform.openai.com/docs/guides/structured-outputs). + - `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: "json_schema"` + - `"eq"` - The type of response format being defined. Always `json_schema`. + - `"ne"` - - `"json_schema"` + - `"gt"` - - `started_at: number` + - `"gte"` - The Unix timestamp (in seconds) for when the run was started. + - `"lt"` - - `status: RunStatus` + - `"lte"` - The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. + - `"in"` - - `"queued"` + - `"nin"` - - `"in_progress"` + - `value: string or number or boolean or array of string or number` - - `"requires_action"` + The value to compare against the attribute key; supports string, number, or boolean types. - - `"cancelling"` + - `string` - - `"cancelled"` + - `number` - - `"failed"` + - `boolean` - - `"completed"` + - `array of string or number` - - `"incomplete"` + - `string` - - `"expired"` + - `number` - - `thread_id: string` + - `CompoundFilter object { filters, type }` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + Combine multiple filters using `and` or `or`. - - `tool_choice: AssistantToolChoiceOption` + - `filters: array of object { key, type, value } or unknown` - 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. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `Auto = "none" or "auto" or "required"` + - `ComparisonFilter object { key, type, value }` - `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. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `"none"` + - `key: string` - - `"auto"` + The key to compare against the value. - - `"required"` + - `type: "eq" or "ne" or "gt" or 5 more` - - `AssistantToolChoice object { type, function }` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - Specifies a tool the model should use. Use to force the model to call a specific 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 - - `type: "function" or "code_interpreter" or "file_search"` + - `"eq"` - The type of the tool. If type is `function`, the function name must be set + - `"ne"` - - `"function"` + - `"gt"` - - `"code_interpreter"` + - `"gte"` - - `"file_search"` + - `"lt"` - - `function: optional AssistantToolChoiceFunction` + - `"lte"` - - `name: string` + - `"in"` - The name of the function to call. + - `"nin"` - - `tools: array of AssistantTool` + - `value: string or number or boolean or array of string or number` - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + The value to compare against the attribute key; supports string, number, or boolean types. - - `CodeInterpreterTool object { type }` + - `string` - - `type: "code_interpreter"` + - `number` - The type of tool being defined: `code_interpreter` + - `boolean` - - `"code_interpreter"` + - `array of string or number` - - `FileSearchTool object { type, file_search }` + - `string` - - `type: "file_search"` + - `number` - The type of tool being defined: `file_search` + - `unknown` - - `"file_search"` + - `type: "and" or "or"` - - `file_search: optional object { max_num_results, ranking_options }` + Type of operation: `and` or `or`. - Overrides for the file search tool. + - `"and"` - - `max_num_results: optional number` + - `"or"` - 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. + - `max_num_results: optional number` - Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `ranking_options: optional object { score_threshold, ranker }` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - 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. + Ranking options for search. - See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `hybrid_search: optional object { embedding_weight, text_weight }` - - `score_threshold: number` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - The score threshold for the file search. All values must be a floating point number between 0 and 1. + - `embedding_weight: number` - - `ranker: optional "auto" or "default_2024_08_21"` + The weight of the embedding in the reciprocal ranking fusion. - The ranker to use for the file search. If not specified will use the `auto` ranker. + - `text_weight: number` - - `"auto"` + The weight of the text in the reciprocal ranking fusion. - - `"default_2024_08_21"` + - `ranker: optional "auto" or "default-2024-11-15"` - - `FunctionTool object { function, type }` + The ranker to use for the file search. - - `function: FunctionDefinition` + - `"auto"` - - `name: string` + - `"default-2024-11-15"` - 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. + - `score_threshold: optional number` - - `description: optional string` + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - A description of what the function does, used by the model to choose when and how to call the function. + - `Computer object { type }` - - `parameters: optional FunctionParameters` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + - `type: "computer"` - Omitting `parameters` defines a function with an empty parameter list. + The type of the computer tool. Always `computer`. - - `strict: optional boolean` + - `"computer"` - 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](https://platform.openai.com/docs/guides/function-calling). + - `ComputerUsePreview object { display_height, display_width, environment, type }` - - `type: "function"` + 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 tool being defined: `function` + - `display_height: number` - - `"function"` + The height of the computer display. - - `truncation_strategy: object { type, last_messages }` + - `display_width: number` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + The width of the computer display. - - `type: "auto" or "last_messages"` + - `environment: "windows" or "mac" or "linux" or 2 more` - 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 type of computer environment to control. - - `"auto"` + - `"windows"` - - `"last_messages"` + - `"mac"` - - `last_messages: optional number` + - `"linux"` - The number of most recent messages from the thread when constructing the context for the run. + - `"ubuntu"` - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + - `"browser"` - 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.). + - `type: "computer_use_preview"` - - `completion_tokens: number` + The type of the computer use tool. Always `computer_use_preview`. - Number of completion tokens used over the course of the run. + - `"computer_use_preview"` - - `prompt_tokens: number` + - `WebSearch object { type, filters, search_context_size, user_location }` - Number of prompt tokens 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). - - `total_tokens: number` + - `type: "web_search" or "web_search_2025_08_26"` - Total number of tokens used (prompt + completion). + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `temperature: optional number` + - `"web_search"` - The sampling temperature used for this run. If not set, defaults to 1. + - `"web_search_2025_08_26"` - - `top_p: optional number` + - `filters: optional object { allowed_domains }` - The nucleus sampling value used for this run. If not set, defaults to 1. + Filters for the search. -### Example + - `allowed_domains: optional array of string` -```http -curl https://api.openai.com/v1/threads/$THREAD_ID/runs/$RUN_ID/cancel \ - -X POST \ - -H 'OpenAI-Beta: assistants=v2' \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. -#### Response + Example: `["pubmed.ncbi.nlm.nih.gov"]` -```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 -} -``` + - `search_context_size: optional "low" or "medium" or "high"` -### Example + 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. -```http -curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/cancel \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "OpenAI-Beta: assistants=v2" \ - -X POST -``` + - `"low"` -#### Response + - `"medium"` -```json -{ - "id": "run_abc123", - "object": "thread.run", - "created_at": 1699076126, - "assistant_id": "asst_abc123", - "thread_id": "thread_abc123", - "status": "cancelling", - "started_at": 1699076126, - "expires_at": 1699076726, - "cancelled_at": null, - "failed_at": null, - "completed_at": null, - "last_error": null, - "model": "gpt-4o", - "instructions": "You summarize books.", - "tools": [ - { - "type": "file_search" - } - ], - "tool_resources": { - "file_search": { - "vector_store_ids": ["vs_123"] - } - }, - "metadata": {}, - "usage": null, - "temperature": 1.0, - "top_p": 1.0, - "response_format": "auto", - "tool_choice": "auto", - "parallel_tool_calls": true -} -``` + - `"high"` -## Domain Types + - `user_location: optional object { city, country, region, 2 more }` -### Required Action Function Tool Call + The approximate location of the user. -- `RequiredActionFunctionToolCall object { id, function, type }` + - `city: optional string` - Tool call objects + 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](https://platform.openai.com/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). -### Run + - `server_label: string` -- `Run object { id, assistant_id, cancelled_at, 24 more }` + A label for this MCP server, used to identify it in tool calls. - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `type: "mcp"` - - `id: string` + The type of the MCP tool. Always `mcp`. - The identifier, which can be referenced in API endpoints. + - `"mcp"` - - `assistant_id: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + The tool invocation context(s). - - `cancelled_at: number` + - `"direct"` - The Unix timestamp (in seconds) for when the run was cancelled. + - `"programmatic"` - - `completed_at: number` + - `allowed_tools: optional array of string or object { read_only, tool_names }` - The Unix timestamp (in seconds) for when the run was completed. + List of allowed tool names or a filter object. - - `created_at: number` + - `McpAllowedTools = array of string` - The Unix timestamp (in seconds) for when the run was created. + A string array of allowed tool names - - `expires_at: number` + - `McpToolFilter object { read_only, tool_names }` - The Unix timestamp (in seconds) for when the run will expire. + A filter object to specify which tools are allowed. - - `failed_at: number` + - `read_only: optional boolean` - The Unix timestamp (in seconds) for when the run 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. - - `incomplete_details: object { reason }` + - `tool_names: optional array of string` - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + List of allowed tool names. - - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` + - `authorization: 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. + 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. - - `"max_completion_tokens"` + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `"max_prompt_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). - - `instructions: string` + Currently supported `connector_id` values are: - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this 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` - - `last_error: object { code, message }` + - `"connector_dropbox"` - The last error associated with this run. Will be `null` if there are no errors. + - `"connector_gmail"` - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` + - `"connector_googlecalendar"` - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + - `"connector_googledrive"` - - `"server_error"` + - `"connector_microsoftteams"` - - `"rate_limit_exceeded"` + - `"connector_outlookcalendar"` - - `"invalid_prompt"` + - `"connector_outlookemail"` - - `message: string` + - `"connector_sharepoint"` - A human-readable description of the error. + - `defer_loading: optional boolean` - - `max_completion_tokens: number` + Whether this MCP tool is deferred and discovered via tool search. - The maximum number of completion tokens specified to have been used over the course of the run. + - `headers: optional map[string]` - - `max_prompt_tokens: number` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - The maximum number of prompt tokens specified to have been used over the course of the run. + - `require_approval: optional object { always, never } or "always" or "never"` - - `metadata: Metadata` + Specify which of the MCP server's tools require approval. - 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. + - `McpToolApprovalFilter object { always, never }` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `model: string` + - `always: optional object { read_only, tool_names }` - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + A filter object to specify which tools are allowed. - - `object: "thread.run"` + - `read_only: optional boolean` - The object type, which is always `thread.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. - - `"thread.run"` + - `tool_names: optional array of string` - - `parallel_tool_calls: boolean` + List of allowed tool names. - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `never: optional object { read_only, tool_names }` - - `required_action: object { submit_tool_outputs, type }` + A filter object to specify which tools are allowed. - Details on the action required to continue the run. Will be `null` if no action is required. + - `read_only: optional boolean` - - `submit_tool_outputs: object { tool_calls }` + 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. - Details on the tool outputs needed for this run to continue. + - `tool_names: optional array of string` - - `tool_calls: array of RequiredActionFunctionToolCall` + List of allowed tool names. - A list of the relevant tool calls. + - `McpToolApprovalSetting = "always" or "never"` - - `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 tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. + - `"always"` - - `function: object { arguments, name }` + - `"never"` - The function definition. + - `server_description: optional string` - - `arguments: string` + Optional description of the MCP server, used to provide more context. - The arguments that the model expects you to pass to the function. + - `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 function. + - `tunnel_id: optional string` - - `type: "function"` + 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 tool call the output is required for. For now, this is always `function`. + - `CodeInterpreter object { container, type, allowed_callers }` - - `"function"` + A tool that runs Python code to help generate a response to a prompt. - - `type: "submit_tool_outputs"` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - For now, this is always `submit_tool_outputs`. + 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. - - `"submit_tool_outputs"` + - `string` - - `response_format: AssistantResponseFormatOption` + The container ID. - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - 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](https://platform.openai.com/docs/guides/structured-outputs). + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `type: "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. + Always `auto`. - `"auto"` - `auto` is the default value + - `file_ids: optional array of string` - - `"auto"` + An optional list of uploaded files to make available to your code. - - `ResponseFormatText object { type }` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - Default response format. Used to generate text responses. + The memory limit for the code interpreter container. - - `type: "text"` + - `"1g"` - The type of response format being defined. Always `text`. + - `"4g"` - - `"text"` + - `"16g"` - - `ResponseFormatJSONObject object { type }` + - `"64g"` - 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. + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `type: "json_object"` + Network access policy for the container. - The type of response format being defined. Always `json_object`. + - `BetaContainerNetworkPolicyDisabled object { type }` - - `"json_object"` + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `ResponseFormatJSONSchema object { json_schema, type }` + - `type: "code_interpreter"` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + The type of the code interpreter tool. Always `code_interpreter`. - - `json_schema: object { name, description, schema, strict }` + - `"code_interpreter"` - Structured Outputs configuration options, including a JSON Schema. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `name: string` + The tool invocation context(s). - 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. + - `"direct"` - - `description: optional string` + - `"programmatic"` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `ProgrammaticToolCalling object { type }` - - `schema: optional map[unknown]` + - `type: "programmatic_tool_calling"` - 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 tool. Always `programmatic_tool_calling`. - - `strict: optional boolean` + - `"programmatic_tool_calling"` - 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](https://platform.openai.com/docs/guides/structured-outputs). + - `ImageGeneration object { type, action, background, 9 more }` - - `type: "json_schema"` + A tool that generates images using the GPT image models. - The type of response format being defined. Always `json_schema`. + - `type: "image_generation"` - - `"json_schema"` + The type of the image generation tool. Always `image_generation`. - - `started_at: number` + - `"image_generation"` - The Unix timestamp (in seconds) for when the run was started. + - `action: optional "generate" or "edit" or "auto"` - - `status: RunStatus` + Whether to generate a new image or edit an existing image. Default: `auto`. - The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. + - `"generate"` - - `"queued"` + - `"edit"` - - `"in_progress"` + - `"auto"` - - `"requires_action"` + - `background: optional "transparent" or "opaque" or "auto"` - - `"cancelling"` + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - - `"cancelled"` + - `"transparent"` - - `"failed"` + - `"opaque"` - - `"completed"` + - `"auto"` - - `"incomplete"` + - `input_fidelity: optional "high" or "low"` - - `"expired"` + 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`. - - `thread_id: string` + - `"high"` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + - `"low"` - - `tool_choice: AssistantToolChoiceOption` + - `input_image_mask: optional object { file_id, image_url }` - 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. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `Auto = "none" or "auto" or "required"` + - `file_id: optional string` - `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 ID for the mask image. - - `"none"` + - `image_url: optional string` - - `"auto"` + Base64-encoded mask image. - - `"required"` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `AssistantToolChoice object { type, function }` + The image generation model to use. Default: `gpt-image-1`. - Specifies a tool the model should use. Use to force the model to call a specific tool. + - `string` - - `type: "function" or "code_interpreter" or "file_search"` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - The type of the tool. If type is `function`, the function name must be set + The image generation model to use. Default: `gpt-image-1`. - - `"function"` + - `"gpt-image-1"` - - `"code_interpreter"` + - `"gpt-image-1-mini"` - - `"file_search"` + - `"gpt-image-1.5"` - - `function: optional AssistantToolChoiceFunction` + - `moderation: optional "auto" or "low"` - - `name: string` + Moderation level for the generated image. Default: `auto`. - The name of the function to call. + - `"auto"` - - `tools: array of AssistantTool` + - `"low"` - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `output_compression: optional number` - - `CodeInterpreterTool object { type }` + Compression level for the output image. Default: 100. - - `type: "code_interpreter"` + - `output_format: optional "png" or "webp" or "jpeg"` - The type of tool being defined: `code_interpreter` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `"code_interpreter"` + - `"png"` - - `FileSearchTool object { type, file_search }` + - `"webp"` - - `type: "file_search"` + - `"jpeg"` - The type of tool being defined: `file_search` + - `partial_images: optional number` - - `"file_search"` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `file_search: optional object { max_num_results, ranking_options }` + - `quality: optional "low" or "medium" or "high" or "auto"` - Overrides for the file search tool. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `max_num_results: optional number` + - `"low"` - 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. + - `"medium"` - Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `"high"` - - `ranking_options: optional object { score_threshold, ranker }` + - `"auto"` - 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. + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `score_threshold: number` + - `string` - The score threshold for the file search. All values must be a floating point number between 0 and 1. + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `ranker: optional "auto" or "default_2024_08_21"` + 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 ranker to use for the file search. If not specified will use the `auto` ranker. + - `"1024x1024"` - - `"auto"` + - `"1024x1536"` - - `"default_2024_08_21"` + - `"1536x1024"` - - `FunctionTool object { function, type }` + - `"auto"` - - `function: FunctionDefinition` + - `LocalShell object { type }` - - `name: string` + A tool that allows the model to execute shell commands in a local environment. - 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: "local_shell"` - - `description: optional string` + The type of the local shell tool. Always `local_shell`. - A description of what the function does, used by the model to choose when and how to call the function. + - `"local_shell"` - - `parameters: optional FunctionParameters` + - `Shell object { type, allowed_callers, environment }` - The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + A tool that allows the model to execute shell commands. - Omitting `parameters` defines a function with an empty parameter list. + - `type: "shell"` - - `strict: optional boolean` + The type of the shell tool. Always `shell`. - 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](https://platform.openai.com/docs/guides/function-calling). + - `"shell"` - - `type: "function"` + - `allowed_callers: optional array of "direct" or "programmatic"` - The type of tool being defined: `function` + The tool invocation context(s). - - `"function"` + - `"direct"` - - `truncation_strategy: object { type, last_messages }` + - `"programmatic"` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - `type: "auto" or "last_messages"` + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - 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`. + - `BetaLocalEnvironment object { type, skills }` - - `"auto"` + - `BetaContainerReference object { container_id, type }` - - `"last_messages"` + - `Custom object { name, type, allowed_callers, 3 more }` - - `last_messages: optional 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 most recent messages from the thread when constructing the context for the run. + - `name: string` - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + The name of the custom tool, used to identify it in tool calls. - 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.). + - `type: "custom"` - - `completion_tokens: number` + The type of the custom tool. Always `custom`. - Number of completion tokens used over the course of the run. + - `"custom"` - - `prompt_tokens: number` + - `allowed_callers: optional array of "direct" or "programmatic"` - Number of prompt tokens used over the course of the run. + The tool invocation context(s). - - `total_tokens: number` + - `"direct"` - Total number of tokens used (prompt + completion). + - `"programmatic"` - - `temperature: optional number` + - `defer_loading: optional boolean` - The sampling temperature used for this run. If not set, defaults to 1. + Whether this tool should be deferred and discovered via tool search. - - `top_p: optional number` + - `description: optional string` - The nucleus sampling value used for this run. If not set, defaults to 1. + Optional description of the custom tool, used to provide more context. -### Run Status + - `format: optional object { type } or object { definition, syntax, type }` -- `RunStatus = "queued" or "in_progress" or "requires_action" or 6 more` + The input format for the custom tool. Default is unconstrained text. - The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. + - `Text object { type }` - - `"queued"` + Unconstrained free-form text. - - `"in_progress"` + - `type: "text"` - - `"requires_action"` + Unconstrained text format. Always `text`. - - `"cancelling"` + - `"text"` - - `"cancelled"` + - `Grammar object { definition, syntax, type }` - - `"failed"` + A grammar defined by the user. - - `"completed"` + - `definition: string` - - `"incomplete"` + The grammar definition. - - `"expired"` + - `syntax: "lark" or "regex"` -# Steps + The syntax of the grammar definition. One of `lark` or `regex`. -## List run steps + - `"lark"` -**get** `/threads/{thread_id}/runs/{run_id}/steps` + - `"regex"` -List run steps + - `type: "grammar"` -### Path Parameters + Grammar format. Always `grammar`. -- `thread_id: string` + - `"grammar"` -- `run_id: string` + - `Namespace object { description, name, tools, type }` -### Query Parameters + Groups function/custom tools under a shared namespace. -- `after: optional string` + - `description: 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. + A description of the namespace shown to the model. -- `before: optional string` + - `name: 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 namespace name used in tool calls (for example, `crm`). -- `include: optional array of RunStepInclude` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - 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. + The function/custom tools available inside this namespace. - See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `Function object { name, type, allowed_callers, 5 more }` - - `"step_details.tool_calls[*].file_search.results[*].content"` + - `name: string` -- `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. + - `"function"` -- `order: optional "asc" or "desc"` + - `allowed_callers: optional array of "direct" or "programmatic"` - Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. + The tool invocation context(s). - - `"asc"` + - `"direct"` - - `"desc"` + - `"programmatic"` -### Returns + - `defer_loading: optional boolean` -- `data: array of RunStep` + Whether this function should be deferred and discovered via tool search. - - `id: string` + - `description: optional string` - The identifier of the run step, which can be referenced in API endpoints. + - `output_schema: optional map[unknown]` - - `assistant_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 [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. + - `parameters: optional unknown` - - `cancelled_at: number` + - `strict: optional boolean` - The Unix timestamp (in seconds) for when the run step was cancelled. + 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_at: number` + - `Custom object { name, type, allowed_callers, 3 more }` - The Unix timestamp (in seconds) for when the run step completed. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `created_at: number` + - `name: string` - The Unix timestamp (in seconds) for when the run step was created. + The name of the custom tool, used to identify it in tool calls. - - `expired_at: number` + - `type: "custom"` - 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 the custom tool. Always `custom`. - - `failed_at: number` + - `"custom"` - The Unix timestamp (in seconds) for when the run step failed. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `last_error: object { code, message }` + The tool invocation context(s). - The last error associated with this run step. Will be `null` if there are no errors. + - `"direct"` - - `code: "server_error" or "rate_limit_exceeded"` + - `"programmatic"` - One of `server_error` or `rate_limit_exceeded`. + - `defer_loading: optional boolean` - - `"server_error"` + Whether this tool should be deferred and discovered via tool search. - - `"rate_limit_exceeded"` + - `description: optional string` - - `message: string` + Optional description of the custom tool, used to provide more context. - A human-readable description of the error. + - `format: optional object { type } or object { definition, syntax, type }` - - `metadata: Metadata` + The input format for the custom tool. Default is unconstrained text. - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `Text object { type }` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + Unconstrained free-form text. - - `object: "thread.run.step"` + - `type: "text"` - The object type, which is always `thread.run.step`. + Unconstrained text format. Always `text`. - - `"thread.run.step"` + - `"text"` - - `run_id: string` + - `Grammar object { definition, syntax, type }` - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. + A grammar defined by the user. - - `status: "in_progress" or "cancelled" or "failed" or 2 more` + - `definition: string` - The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. + The grammar definition. - - `"in_progress"` + - `syntax: "lark" or "regex"` - - `"cancelled"` + The syntax of the grammar definition. One of `lark` or `regex`. - - `"failed"` + - `"lark"` - - `"completed"` + - `"regex"` - - `"expired"` + - `type: "grammar"` - - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` + Grammar format. Always `grammar`. - The details of the run step. + - `"grammar"` - - `MessageCreationStepDetails object { message_creation, type }` + - `type: "namespace"` - Details of the message creation by the run step. + The type of the tool. Always `namespace`. - - `message_creation: object { message_id }` + - `"namespace"` - - `message_id: string` + - `ToolSearch object { type, description, execution, parameters }` - The ID of the message that was created by this run step. + Hosted or BYOT tool search configuration for deferred tools. - - `type: "message_creation"` + - `type: "tool_search"` - Always `message_creation`. + The type of the tool. Always `tool_search`. - - `"message_creation"` + - `"tool_search"` - - `ToolCallsStepDetails object { tool_calls, type }` + - `description: optional string` - Details of the tool call. + Description shown to the model for a client-executed tool search tool. - - `tool_calls: array of ToolCall` + - `execution: optional "server" or "client"` - 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`. + Whether tool search is executed by the server or by the client. - - `CodeInterpreterToolCall object { id, code_interpreter, type }` + - `"server"` - Details of the Code Interpreter tool call the run step was involved in. + - `"client"` - - `id: string` + - `parameters: optional unknown` - The ID of the tool call. + Parameter schema for a client-executed tool search tool. - - `code_interpreter: object { input, outputs }` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - The Code Interpreter tool call definition. + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `input: string` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - The input to the Code Interpreter tool call. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `outputs: array of object { logs, type } or object { image, type }` + - `"web_search_preview"` - 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. + - `"web_search_preview_2025_03_11"` - - `Logs object { logs, type }` + - `search_content_types: optional array of "text" or "image"` - Text output from the Code Interpreter tool call as part of a run step. + - `"text"` - - `logs: string` + - `"image"` - The text output from the Code Interpreter tool call. + - `search_context_size: optional "low" or "medium" or "high"` - - `type: "logs"` + 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. - Always `logs`. + - `"low"` - - `"logs"` + - `"medium"` - - `Image object { image, type }` + - `"high"` - - `image: object { file_id }` + - `user_location: optional object { type, city, country, 2 more }` - - `file_id: string` + The user's location. - The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. + - `type: "approximate"` - - `type: "image"` + The type of location approximation. Always `approximate`. - Always `image`. + - `"approximate"` - - `"image"` + - `city: optional string` - - `type: "code_interpreter"` + Free text input for the city of the user, e.g. `San Francisco`. - The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + - `country: optional string` - - `"code_interpreter"` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `FileSearchToolCall object { id, file_search, type }` + - `region: optional string` - - `id: string` + Free text input for the region of the user, e.g. `California`. - The ID of the tool call object. + - `timezone: optional string` - - `file_search: object { ranking_options, results }` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - For now, this is always going to be an empty object. + - `ApplyPatch object { type, allowed_callers }` - - `ranking_options: optional object { ranker, score_threshold }` + Allows the assistant to create, delete, or update files using unified diffs. - The ranking options for the file search. + - `type: "apply_patch"` - - `ranker: "auto" or "default_2024_08_21"` + The type of the tool. Always `apply_patch`. - The ranker to use for the file search. If not specified will use the `auto` ranker. + - `"apply_patch"` - - `"auto"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"default_2024_08_21"` + The tool invocation context(s). - - `score_threshold: number` + - `"direct"` - The score threshold for the file search. All values must be a floating point number between 0 and 1. + - `"programmatic"` - - `results: optional array of object { file_id, file_name, score, content }` + - `type: "tool_search_output"` - The results of the file search. + The type of the item. Always `tool_search_output`. - - `file_id: string` + - `"tool_search_output"` - The ID of the file that result was found in. + - `agent: optional object { agent_name }` - - `file_name: string` + The agent that produced this item. - The name of the file that result was found in. + - `agent_name: string` - - `score: number` + The canonical name of the agent that produced this item. - The score of the result. All values must be a floating point number between 0 and 1. + - `created_by: optional string` - - `content: optional array of object { text, type }` + The identifier of the actor that created the item. - The content of the result that was found. The content is only included if requested via the include query parameter. + - `AdditionalTools object { id, role, tools, 2 more }` - - `text: optional string` + - `id: string` - The text content of the file. + The unique ID of the additional tools item. - - `type: optional "text"` + - `role: "unknown" or "user" or "assistant" or 5 more` - The type of the content. + The role that provided the additional tools. - - `"text"` + - `"unknown"` - - `type: "file_search"` + - `"user"` - The type of tool call. This is always going to be `file_search` for this type of tool call. + - `"assistant"` - - `"file_search"` + - `"system"` - - `FunctionToolCall object { id, function, type }` + - `"critic"` - - `id: string` + - `"discriminator"` - The ID of the tool call object. + - `"developer"` - - `function: object { arguments, name, output }` + - `"tool"` - The definition of the function that was called. + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - - `arguments: string` + The additional tool definitions made available at this item. - The arguments passed to the function. + - `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. + The name of the function to call. - - `output: string` + - `parameters: map[unknown]` + + A JSON schema object describing the parameters of the function. - The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. + - `strict: boolean` + + Whether strict parameter validation is enforced for this function tool. - `type: "function"` - The type of tool call. This is always going to be `function` for this type of tool call. + The type of the function tool. Always `function`. - `"function"` - - `type: "tool_calls"` + - `allowed_callers: optional array of "direct" or "programmatic"` - Always `tool_calls`. + The tool invocation context(s). - - `"tool_calls"` + - `"direct"` - - `thread_id: string` + - `"programmatic"` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. + - `defer_loading: optional boolean` - - `type: "message_creation" or "tool_calls"` + Whether this function is deferred and loaded via tool search. - The type of run step, which can be either `message_creation` or `tool_calls`. + - `description: optional string` - - `"message_creation"` + A description of the function. Used by the model to determine whether or not to call the function. - - `"tool_calls"` + - `output_schema: optional map[unknown]` - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + A JSON schema object describing the JSON value encoded in string outputs for this function. - Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - - `completion_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). - Number of completion tokens used over the course of the run step. + - `type: "file_search"` - - `prompt_tokens: number` + The type of the file search tool. Always `file_search`. - Number of prompt tokens used over the course of the run step. + - `"file_search"` - - `total_tokens: number` + - `vector_store_ids: array of string` - Total number of tokens used (prompt + completion). + The IDs of the vector stores to search. -- `first_id: string` + - `filters: optional object { key, type, value } or object { filters, type }` -- `has_more: boolean` + A filter to apply. -- `last_id: string` + - `ComparisonFilter object { key, type, value }` -- `object: string` + 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/threads/$THREAD_ID/runs/$RUN_ID/steps \ - -H 'OpenAI-Beta: assistants=v2' \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + The key to compare against the value. -#### Response + - `type: "eq" or "ne" or "gt" or 5 more` -```json -{ - "data": [ - { - "id": "id", - "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 - } - } - ], - "first_id": "step_abc123", - "has_more": false, - "last_id": "step_abc456", - "object": "list" -} -``` + 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/threads/thread_abc123/runs/run_abc123/steps \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "Content-Type: application/json" \ - -H "OpenAI-Beta: assistants=v2" -``` + - `"eq"` -#### Response + - `"ne"` -```json -{ - "object": "list", - "data": [ - { - "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 - } - } - ], - "first_id": "step_abc123", - "last_id": "step_abc456", - "has_more": false -} -``` + - `"gt"` -## Retrieve run step + - `"gte"` -**get** `/threads/{thread_id}/runs/{run_id}/steps/{step_id}` + - `"lt"` -Retrieve run step + - `"lte"` -### Path Parameters + - `"in"` -- `thread_id: string` + - `"nin"` -- `run_id: string` + - `value: string or number or boolean or array of string or number` -- `step_id: string` + The value to compare against the attribute key; supports string, number, or boolean types. -### Query Parameters + - `string` -- `include: optional array of RunStepInclude` + - `number` - 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. + - `boolean` - See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `array of string or number` - - `"step_details.tool_calls[*].file_search.results[*].content"` + - `string` -### Returns + - `number` -- `RunStep object { id, assistant_id, cancelled_at, 13 more }` + - `CompoundFilter object { filters, type }` - Represents a step in execution of a run. + Combine multiple filters using `and` or `or`. - - `id: string` + - `filters: array of object { key, type, value } or unknown` - The identifier of the run step, which can be referenced in API endpoints. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `assistant_id: string` + - `ComparisonFilter object { key, type, value }` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `cancelled_at: number` + - `key: string` - The Unix timestamp (in seconds) for when the run step was cancelled. + The key to compare against the value. - - `completed_at: number` + - `type: "eq" or "ne" or "gt" or 5 more` - The Unix timestamp (in seconds) for when the run step completed. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `created_at: 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 Unix timestamp (in seconds) for when the run step was created. + - `"eq"` - - `expired_at: number` + - `"ne"` - The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. + - `"gt"` - - `failed_at: number` + - `"gte"` - The Unix timestamp (in seconds) for when the run step failed. + - `"lt"` - - `last_error: object { code, message }` + - `"lte"` - The last error associated with this run step. Will be `null` if there are no errors. + - `"in"` - - `code: "server_error" or "rate_limit_exceeded"` + - `"nin"` - One of `server_error` or `rate_limit_exceeded`. + - `value: string or number or boolean or array of string or number` - - `"server_error"` + The value to compare against the attribute key; supports string, number, or boolean types. - - `"rate_limit_exceeded"` + - `string` - - `message: string` + - `number` - A human-readable description of the error. + - `boolean` - - `metadata: Metadata` + - `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. + - `string` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `number` - - `object: "thread.run.step"` + - `unknown` - The object type, which is always `thread.run.step`. + - `type: "and" or "or"` - - `"thread.run.step"` + Type of operation: `and` or `or`. - - `run_id: string` + - `"and"` - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. + - `"or"` - - `status: "in_progress" or "cancelled" or "failed" or 2 more` + - `max_num_results: optional number` - The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. + 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 }` - - `"cancelled"` + Ranking options for search. - - `"failed"` + - `hybrid_search: optional object { embedding_weight, text_weight }` - - `"completed"` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `"expired"` + - `embedding_weight: number` - - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` + The weight of the embedding in the reciprocal ranking fusion. - The details of the run step. + - `text_weight: number` - - `MessageCreationStepDetails object { message_creation, type }` + The weight of the text in the reciprocal ranking fusion. - Details of the message creation by the run step. + - `ranker: optional "auto" or "default-2024-11-15"` - - `message_creation: object { message_id }` + The ranker to use for the file search. - - `message_id: string` + - `"auto"` - The ID of the message that was created by this run step. + - `"default-2024-11-15"` - - `type: "message_creation"` + - `score_threshold: optional number` - Always `message_creation`. + 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. - - `"message_creation"` + - `Computer object { type }` - - `ToolCallsStepDetails object { tool_calls, type }` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - Details of the tool call. + - `type: "computer"` - - `tool_calls: array of ToolCall` + The type of the computer tool. Always `computer`. - 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`. + - `"computer"` - - `CodeInterpreterToolCall object { id, code_interpreter, type }` + - `ComputerUsePreview object { display_height, display_width, environment, type }` - Details of the Code Interpreter tool call the run step was involved in. + 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 ID of the tool call. + The height of the computer display. - - `code_interpreter: object { input, outputs }` + - `display_width: number` - The Code Interpreter tool call definition. + The width of the computer display. - - `input: string` + - `environment: "windows" or "mac" or "linux" or 2 more` - The input to the Code Interpreter tool call. + The type of computer environment to control. - - `outputs: array of object { logs, type } or object { image, type }` + - `"windows"` - 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. + - `"mac"` - - `Logs object { logs, type }` + - `"linux"` - Text output from the Code Interpreter tool call as part of a run step. + - `"ubuntu"` - - `logs: string` + - `"browser"` - The text output from the Code Interpreter tool call. + - `type: "computer_use_preview"` - - `type: "logs"` + The type of the computer use tool. Always `computer_use_preview`. - Always `logs`. + - `"computer_use_preview"` - - `"logs"` + - `WebSearch object { type, filters, search_context_size, user_location }` - - `Image object { image, type }` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - - `image: object { file_id }` + - `type: "web_search" or "web_search_2025_08_26"` - - `file_id: string` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. + - `"web_search"` - - `type: "image"` + - `"web_search_2025_08_26"` - Always `image`. + - `filters: optional object { allowed_domains }` - - `"image"` + Filters for the search. - - `type: "code_interpreter"` + - `allowed_domains: optional array of string` - The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `"code_interpreter"` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `FileSearchToolCall object { id, file_search, type }` + - `search_context_size: optional "low" or "medium" or "high"` - - `id: string` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - The ID of the tool call object. + - `"low"` - - `file_search: object { ranking_options, results }` + - `"medium"` - For now, this is always going to be an empty object. + - `"high"` - - `ranking_options: optional object { ranker, score_threshold }` + - `user_location: optional object { city, country, region, 2 more }` - The ranking options for the file search. + The approximate location of the user. - - `ranker: "auto" or "default_2024_08_21"` + - `city: optional string` - The ranker to use for the file search. If not specified will use the `auto` ranker. + Free text input for the city of the user, e.g. `San Francisco`. - - `"auto"` + - `country: optional string` - - `"default_2024_08_21"` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `score_threshold: number` + - `region: optional string` - The score threshold for the file search. All values must be a floating point number between 0 and 1. + Free text input for the region of the user, e.g. `California`. - - `results: optional array of object { file_id, file_name, score, content }` + - `timezone: optional string` - The results of the file search. + 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 that result was found in. + The type of location approximation. Always `approximate`. - - `file_name: string` + - `"approximate"` - The name of the file that result was found in. + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `score: 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 score of the result. All values must be a floating point number between 0 and 1. + - `server_label: string` - - `content: optional array of object { text, type }` + A label for this MCP server, used to identify it in tool calls. - The content of the result that was found. The content is only included if requested via the include query parameter. + - `type: "mcp"` - - `text: optional string` + The type of the MCP tool. Always `mcp`. - The text content of the file. + - `"mcp"` - - `type: optional "text"` + - `allowed_callers: optional array of "direct" or "programmatic"` - The type of the content. + The tool invocation context(s). - - `"text"` + - `"direct"` - - `type: "file_search"` + - `"programmatic"` - The type of tool call. This is always going to be `file_search` for this type of tool call. + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `"file_search"` + List of allowed tool names or a filter object. - - `FunctionToolCall object { id, function, type }` + - `McpAllowedTools = array of string` - - `id: string` + A string array of allowed tool names - The ID of the tool call object. + - `McpToolFilter object { read_only, tool_names }` - - `function: object { arguments, name, output }` + A filter object to specify which tools are allowed. - The definition of the function that was called. + - `read_only: optional boolean` - - `arguments: 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 arguments passed to the function. + - `tool_names: optional array of string` - - `name: string` + List of allowed tool names. - The name of the function. + - `authorization: optional string` - - `output: string` + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `type: "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). - The type of tool call. This is always going to be `function` for this type of tool call. + Currently supported `connector_id` values are: - - `"function"` + - 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: "tool_calls"` + - `"connector_dropbox"` - Always `tool_calls`. + - `"connector_gmail"` - - `"tool_calls"` + - `"connector_googlecalendar"` - - `thread_id: string` + - `"connector_googledrive"` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. + - `"connector_microsoftteams"` - - `type: "message_creation" or "tool_calls"` + - `"connector_outlookcalendar"` - The type of run step, which can be either `message_creation` or `tool_calls`. + - `"connector_outlookemail"` - - `"message_creation"` + - `"connector_sharepoint"` - - `"tool_calls"` + - `defer_loading: optional boolean` - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + Whether this MCP tool is deferred and discovered via tool search. - Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. + - `headers: optional map[string]` - - `completion_tokens: number` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - Number of completion tokens used over the course of the run step. + - `require_approval: optional object { always, never } or "always" or "never"` - - `prompt_tokens: number` + Specify which of the MCP server's tools require approval. - Number of prompt tokens used over the course of the run step. + - `McpToolApprovalFilter object { always, never }` - - `total_tokens: 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. - Total number of tokens used (prompt + completion). + - `always: optional object { read_only, tool_names }` -### Example + A filter object to specify which tools are allowed. -```http -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" -``` + - `read_only: optional boolean` -#### 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. -```json -{ - "id": "id", - "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 - } -} -``` + - `tool_names: optional array of string` -### Example + List of allowed tool names. -```http -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" -``` + - `never: optional object { read_only, tool_names }` -#### Response + A filter object to specify which tools are allowed. -```json -{ - "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 - } -} -``` + - `read_only: optional boolean` -## Domain Types + 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 Interpreter Logs + - `tool_names: optional array of string` -- `CodeInterpreterLogs object { index, type, logs }` + List of allowed tool names. - Text output from the Code Interpreter tool call as part of a run step. + - `McpToolApprovalSetting = "always" or "never"` - - `index: number` + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - The index of the output in the outputs array. + - `"always"` - - `type: "logs"` + - `"never"` - Always `logs`. + - `server_description: optional string` - - `"logs"` + Optional description of the MCP server, used to provide more context. - - `logs: optional string` + - `server_url: optional string` - The text output from the Code Interpreter tool call. + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. -### Code Interpreter Output Image + - `tunnel_id: optional string` -- `CodeInterpreterOutputImage object { index, type, 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. - - `index: number` + - `CodeInterpreter object { container, type, allowed_callers }` - The index of the output in the outputs array. + A tool that runs Python code to help generate a response to a prompt. - - `type: "image"` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - Always `image`. + 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. - - `"image"` + - `string` - - `image: optional object { file_id }` + The container ID. - - `file_id: optional string` + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. -### Code Interpreter Tool Call + - `type: "auto"` -- `CodeInterpreterToolCall object { id, code_interpreter, type }` + Always `auto`. - Details of the Code Interpreter tool call the run step was involved in. + - `"auto"` - - `id: string` + - `file_ids: optional array of string` - The ID of the tool call. + An optional list of uploaded files to make available to your code. - - `code_interpreter: object { input, outputs }` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - The Code Interpreter tool call definition. + The memory limit for the code interpreter container. - - `input: string` + - `"1g"` - The input to the Code Interpreter tool call. + - `"4g"` - - `outputs: array of object { logs, type } or object { image, type }` + - `"16g"` - 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. + - `"64g"` - - `Logs object { logs, type }` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - Text output from the Code Interpreter tool call as part of a run step. + Network access policy for the container. - - `logs: string` + - `BetaContainerNetworkPolicyDisabled object { type }` - The text output from the Code Interpreter tool call. + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `type: "logs"` + - `type: "code_interpreter"` - Always `logs`. + The type of the code interpreter tool. Always `code_interpreter`. - - `"logs"` + - `"code_interpreter"` - - `Image object { image, type }` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `image: object { file_id }` + The tool invocation context(s). - - `file_id: string` + - `"direct"` - The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. + - `"programmatic"` - - `type: "image"` + - `ProgrammaticToolCalling object { type }` - Always `image`. + - `type: "programmatic_tool_calling"` - - `"image"` + The type of the tool. Always `programmatic_tool_calling`. - - `type: "code_interpreter"` + - `"programmatic_tool_calling"` - The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + - `ImageGeneration object { type, action, background, 9 more }` - - `"code_interpreter"` + A tool that generates images using the GPT image models. -### Code Interpreter Tool Call Delta + - `type: "image_generation"` -- `CodeInterpreterToolCallDelta object { index, type, id, code_interpreter }` + The type of the image generation tool. Always `image_generation`. - Details of the Code Interpreter tool call the run step was involved in. + - `"image_generation"` - - `index: number` + - `action: optional "generate" or "edit" or "auto"` - The index of the tool call in the tool calls array. + Whether to generate a new image or edit an existing image. Default: `auto`. - - `type: "code_interpreter"` + - `"generate"` - The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + - `"edit"` - - `"code_interpreter"` + - `"auto"` - - `id: optional string` + - `background: optional "transparent" or "opaque" or "auto"` - The ID of the tool call. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - - `code_interpreter: optional object { input, outputs }` + - `"transparent"` - The Code Interpreter tool call definition. + - `"opaque"` - - `input: optional string` + - `"auto"` - The input to the Code Interpreter tool call. + - `input_fidelity: optional "high" or "low"` - - `outputs: optional array of CodeInterpreterLogs or CodeInterpreterOutputImage` + 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 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"` - - `CodeInterpreterLogs object { index, type, logs }` + - `"low"` - Text output from the Code Interpreter tool call as part of a run step. + - `input_image_mask: optional object { file_id, image_url }` - - `index: number` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - The index of the output in the outputs array. + - `file_id: optional string` - - `type: "logs"` + File ID for the mask image. - Always `logs`. + - `image_url: optional string` - - `"logs"` + Base64-encoded mask image. - - `logs: optional string` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - The text output from the Code Interpreter tool call. + The image generation model to use. Default: `gpt-image-1`. - - `CodeInterpreterOutputImage object { index, type, image }` + - `string` - - `index: number` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - The index of the output in the outputs array. + The image generation model to use. Default: `gpt-image-1`. - - `type: "image"` + - `"gpt-image-1"` - Always `image`. + - `"gpt-image-1-mini"` - - `"image"` + - `"gpt-image-1.5"` - - `image: optional object { file_id }` + - `moderation: optional "auto" or "low"` - - `file_id: optional string` + Moderation level for the generated image. Default: `auto`. - The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. + - `"auto"` -### File Search Tool Call + - `"low"` -- `FileSearchToolCall object { id, file_search, type }` + - `output_compression: optional number` - - `id: string` + Compression level for the output image. Default: 100. - The ID of the tool call object. + - `output_format: optional "png" or "webp" or "jpeg"` - - `file_search: object { ranking_options, results }` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - For now, this is always going to be an empty object. + - `"png"` - - `ranking_options: optional object { ranker, score_threshold }` + - `"webp"` - The ranking options for the file search. + - `"jpeg"` - - `ranker: "auto" or "default_2024_08_21"` + - `partial_images: optional number` - The ranker to use for the file search. If not specified will use the `auto` ranker. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `"auto"` + - `quality: optional "low" or "medium" or "high" or "auto"` - - `"default_2024_08_21"` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `score_threshold: number` + - `"low"` - The score threshold for the file search. All values must be a floating point number between 0 and 1. + - `"medium"` - - `results: optional array of object { file_id, file_name, score, content }` + - `"high"` - The results of the file search. + - `"auto"` - - `file_id: string` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - The ID of the file that result was found in. + 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_name: string` + - `string` - The name of the file that result was found in. + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `score: 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 score of the result. All values must be a floating point number between 0 and 1. + - `"1024x1024"` - - `content: optional array of object { text, type }` + - `"1024x1536"` - The content of the result that was found. The content is only included if requested via the include query parameter. + - `"1536x1024"` - - `text: optional string` + - `"auto"` - The text content of the file. + - `LocalShell object { type }` - - `type: optional "text"` + A tool that allows the model to execute shell commands in a local environment. - The type of the content. + - `type: "local_shell"` - - `"text"` + The type of the local shell tool. Always `local_shell`. - - `type: "file_search"` + - `"local_shell"` - The type of tool call. This is always going to be `file_search` for this type of tool call. + - `Shell object { type, allowed_callers, environment }` - - `"file_search"` + A tool that allows the model to execute shell commands. -### File Search Tool Call Delta + - `type: "shell"` -- `FileSearchToolCallDelta object { file_search, index, type, id }` + The type of the shell tool. Always `shell`. - - `file_search: unknown` + - `"shell"` - For now, this is always going to be an empty object. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `index: number` + The tool invocation context(s). - The index of the tool call in the tool calls array. + - `"direct"` - - `type: "file_search"` + - `"programmatic"` - The type of tool call. This is always going to be `file_search` for this type of tool call. + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - `"file_search"` + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - - `id: optional string` + - `BetaLocalEnvironment object { type, skills }` - The ID of the tool call object. + - `BetaContainerReference object { container_id, type }` -### Function Tool Call + - `Custom object { name, type, allowed_callers, 3 more }` -- `FunctionToolCall object { id, function, type }` + 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 ID of the tool call object. + The name of the custom tool, used to identify it in tool calls. - - `function: object { arguments, name, output }` + - `type: "custom"` - The definition of the function that was called. + The type of the custom tool. Always `custom`. - - `arguments: string` + - `"custom"` - The arguments passed to the function. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `name: string` + The tool invocation context(s). - The name of the function. + - `"direct"` - - `output: string` + - `"programmatic"` - The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. + - `defer_loading: optional boolean` - - `type: "function"` + Whether this tool should be deferred and discovered via tool search. - The type of tool call. This is always going to be `function` for this type of tool call. + - `description: optional string` - - `"function"` + Optional description of the custom tool, used to provide more context. -### Function Tool Call Delta + - `format: optional object { type } or object { definition, syntax, type }` -- `FunctionToolCallDelta object { index, type, id, function }` + The input format for the custom tool. Default is unconstrained text. - - `index: number` + - `Text object { type }` - The index of the tool call in the tool calls array. + Unconstrained free-form text. - - `type: "function"` + - `type: "text"` - The type of tool call. This is always going to be `function` for this type of tool call. + Unconstrained text format. Always `text`. - - `"function"` + - `"text"` - - `id: optional string` + - `Grammar object { definition, syntax, type }` - The ID of the tool call object. + A grammar defined by the user. - - `function: optional object { arguments, name, output }` + - `definition: string` - The definition of the function that was called. + The grammar definition. - - `arguments: optional string` + - `syntax: "lark" or "regex"` - The arguments passed to the function. + The syntax of the grammar definition. One of `lark` or `regex`. - - `name: optional string` + - `"lark"` - The name of the function. + - `"regex"` - - `output: optional string` + - `type: "grammar"` - The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. + Grammar format. Always `grammar`. -### Message Creation Step Details + - `"grammar"` -- `MessageCreationStepDetails object { message_creation, type }` + - `Namespace object { description, name, tools, type }` - Details of the message creation by the run step. + Groups function/custom tools under a shared namespace. - - `message_creation: object { message_id }` + - `description: string` - - `message_id: string` + A description of the namespace shown to the model. - The ID of the message that was created by this run step. + - `name: string` - - `type: "message_creation"` + The namespace name used in tool calls (for example, `crm`). - Always `message_creation`. + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - - `"message_creation"` + The function/custom tools available inside this namespace. -### Run Step + - `Function object { name, type, allowed_callers, 5 more }` -- `RunStep object { id, assistant_id, cancelled_at, 13 more }` + - `name: string` - Represents a step in execution of a run. + - `type: "function"` - - `id: string` + - `"function"` - The identifier of the run step, which can be referenced in API endpoints. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `assistant_id: string` + The tool invocation context(s). - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. + - `"direct"` - - `cancelled_at: number` + - `"programmatic"` - The Unix timestamp (in seconds) for when the run step was cancelled. + - `defer_loading: optional boolean` - - `completed_at: number` + Whether this function should be deferred and discovered via tool search. - The Unix timestamp (in seconds) for when the run step completed. + - `description: optional string` - - `created_at: number` + - `output_schema: optional map[unknown]` - The Unix timestamp (in seconds) for when the run step was created. + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `expired_at: number` + - `parameters: optional unknown` - The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. + - `strict: optional boolean` - - `failed_at: 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 Unix timestamp (in seconds) for when the run step failed. + - `Custom object { name, type, allowed_callers, 3 more }` - - `last_error: object { code, message }` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - The last error associated with this run step. Will be `null` if there are no errors. + - `name: string` - - `code: "server_error" or "rate_limit_exceeded"` + The name of the custom tool, used to identify it in tool calls. - One of `server_error` or `rate_limit_exceeded`. + - `type: "custom"` - - `"server_error"` + The type of the custom tool. Always `custom`. - - `"rate_limit_exceeded"` + - `"custom"` - - `message: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - A human-readable description of the error. + The tool invocation context(s). - - `metadata: Metadata` + - `"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. + - `"programmatic"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `defer_loading: optional boolean` - - `object: "thread.run.step"` + Whether this tool should be deferred and discovered via tool search. - The object type, which is always `thread.run.step`. + - `description: optional string` - - `"thread.run.step"` + Optional description of the custom tool, used to provide more context. - - `run_id: string` + - `format: optional object { type } or object { definition, syntax, type }` - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. + The input format for the custom tool. Default is unconstrained text. - - `status: "in_progress" or "cancelled" or "failed" or 2 more` + - `Text object { type }` - The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. + Unconstrained free-form text. - - `"in_progress"` + - `type: "text"` - - `"cancelled"` + Unconstrained text format. Always `text`. - - `"failed"` + - `"text"` - - `"completed"` + - `Grammar object { definition, syntax, type }` - - `"expired"` + A grammar defined by the user. - - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` + - `definition: string` - The details of the run step. + The grammar definition. - - `MessageCreationStepDetails object { message_creation, type }` + - `syntax: "lark" or "regex"` - Details of the message creation by the run step. + The syntax of the grammar definition. One of `lark` or `regex`. - - `message_creation: object { message_id }` + - `"lark"` - - `message_id: string` + - `"regex"` - The ID of the message that was created by this run step. + - `type: "grammar"` - - `type: "message_creation"` + Grammar format. Always `grammar`. - Always `message_creation`. + - `"grammar"` - - `"message_creation"` + - `type: "namespace"` - - `ToolCallsStepDetails object { tool_calls, type }` + The type of the tool. Always `namespace`. - Details of the tool call. + - `"namespace"` - - `tool_calls: array of ToolCall` + - `ToolSearch object { type, description, execution, parameters }` - 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`. + Hosted or BYOT tool search configuration for deferred tools. - - `CodeInterpreterToolCall object { id, code_interpreter, type }` + - `type: "tool_search"` - Details of the Code Interpreter tool call the run step was involved in. + The type of the tool. Always `tool_search`. - - `id: string` + - `"tool_search"` - The ID of the tool call. + - `description: optional string` - - `code_interpreter: object { input, outputs }` + Description shown to the model for a client-executed tool search tool. - The Code Interpreter tool call definition. + - `execution: optional "server" or "client"` - - `input: string` + Whether tool search is executed by the server or by the client. - The input to the Code Interpreter tool call. + - `"server"` - - `outputs: array of object { logs, type } or object { image, type }` + - `"client"` - 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. + - `parameters: optional unknown` - - `Logs object { logs, type }` + Parameter schema for a client-executed tool search tool. - Text output from the Code Interpreter tool call as part of a run step. + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - - `logs: string` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - The text output from the Code Interpreter tool call. + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `type: "logs"` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - Always `logs`. + - `"web_search_preview"` - - `"logs"` + - `"web_search_preview_2025_03_11"` - - `Image object { image, type }` + - `search_content_types: optional array of "text" or "image"` - - `image: object { file_id }` + - `"text"` - - `file_id: string` + - `"image"` - The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. + - `search_context_size: optional "low" or "medium" or "high"` - - `type: "image"` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - Always `image`. + - `"low"` - - `"image"` + - `"medium"` - - `type: "code_interpreter"` + - `"high"` - The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + - `user_location: optional object { type, city, country, 2 more }` - - `"code_interpreter"` + The user's location. - - `FileSearchToolCall object { id, file_search, type }` + - `type: "approximate"` - - `id: string` + The type of location approximation. Always `approximate`. - The ID of the tool call object. + - `"approximate"` - - `file_search: object { ranking_options, results }` + - `city: optional string` - For now, this is always going to be an empty object. + Free text input for the city of the user, e.g. `San Francisco`. - - `ranking_options: optional object { ranker, score_threshold }` + - `country: optional string` - The ranking options for the file search. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `ranker: "auto" or "default_2024_08_21"` + - `region: optional string` - The ranker to use for the file search. If not specified will use the `auto` ranker. + Free text input for the region of the user, e.g. `California`. - - `"auto"` + - `timezone: optional string` - - `"default_2024_08_21"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `score_threshold: number` + - `ApplyPatch object { type, allowed_callers }` - The score threshold for the file search. All values must be a floating point number between 0 and 1. + Allows the assistant to create, delete, or update files using unified diffs. - - `results: optional array of object { file_id, file_name, score, content }` + - `type: "apply_patch"` - The results of the file search. + The type of the tool. Always `apply_patch`. - - `file_id: string` + - `"apply_patch"` - The ID of the file that result was found in. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `file_name: string` + The tool invocation context(s). - The name of the file that result was found in. + - `"direct"` - - `score: number` + - `"programmatic"` - The score of the result. All values must be a floating point number between 0 and 1. + - `type: "additional_tools"` - - `content: optional array of object { text, type }` + The type of the item. Always `additional_tools`. - The content of the result that was found. The content is only included if requested via the include query parameter. + - `"additional_tools"` - - `text: optional string` + - `agent: optional object { agent_name }` - The text content of the file. + The agent that produced this item. - - `type: optional "text"` + - `agent_name: string` - The type of the content. + The canonical name of the agent that produced this item. - - `"text"` + - `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 tool call. This is always going to be `file_search` for this type of tool call. + - `id: string` - - `"file_search"` + The unique ID of the compaction item. - - `FunctionToolCall object { id, function, type }` + - `encrypted_content: string` - - `id: string` + The encrypted content that was produced by compaction. - The ID of the tool call object. + - `type: "compaction"` - - `function: object { arguments, name, output }` + The type of the item. Always `compaction`. - The definition of the function that was called. + - `"compaction"` - - `arguments: string` + - `agent: optional object { agent_name }` - The arguments passed to the function. + The agent that produced this item. - - `name: string` + - `agent_name: string` - The name of the function. + The canonical name of the agent that produced this item. - - `output: string` + - `created_by: optional string` - The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. + The identifier of the actor that created the item. - - `type: "function"` + - `ImageGenerationCall object { id, result, status, 2 more }` - The type of tool call. This is always going to be `function` for this type of tool call. + An image generation request made by the model. - - `"function"` + - `id: string` - - `type: "tool_calls"` + The unique ID of the image generation call. - Always `tool_calls`. + - `result: string` - - `"tool_calls"` + The generated image encoded in base64. - - `thread_id: string` + - `status: "in_progress" or "completed" or "generating" or "failed"` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. + The status of the image generation call. - - `type: "message_creation" or "tool_calls"` + - `"in_progress"` - The type of run step, which can be either `message_creation` or `tool_calls`. + - `"completed"` - - `"message_creation"` + - `"generating"` - - `"tool_calls"` + - `"failed"` - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + - `type: "image_generation_call"` - Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. + The type of the image generation call. Always `image_generation_call`. - - `completion_tokens: number` + - `"image_generation_call"` - Number of completion tokens used over the course of the run step. + - `agent: optional object { agent_name }` - - `prompt_tokens: number` + The agent that produced this item. - Number of prompt tokens used over the course of the run step. + - `agent_name: string` - - `total_tokens: number` + The canonical name of the agent that produced this item. - Total number of tokens used (prompt + completion). + - `CodeInterpreterCall object { id, code, container_id, 4 more }` -### Run Step Delta + A tool call to run code. -- `RunStepDelta object { step_details }` + - `id: string` - The delta containing the fields that have changed on the run step. + The unique ID of the code interpreter tool call. - - `step_details: optional RunStepDeltaMessageDelta or ToolCallDeltaObject` + - `code: string` - The details of the run step. + The code to run, or null if not available. - - `RunStepDeltaMessageDelta object { type, message_creation }` + - `container_id: string` - Details of the message creation by the run step. + The ID of the container used to run the code. - - `type: "message_creation"` + - `outputs: array of object { logs, type } or object { type, url }` - Always `message_creation`. + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `"message_creation"` + - `Logs object { logs, type }` - - `message_creation: optional object { message_id }` + The logs output from the code interpreter. - - `message_id: optional string` + - `logs: string` - The ID of the message that was created by this run step. + The logs output from the code interpreter. - - `ToolCallDeltaObject object { type, tool_calls }` + - `type: "logs"` - Details of the tool call. + The type of the output. Always `logs`. - - `type: "tool_calls"` + - `"logs"` - Always `tool_calls`. + - `Image object { type, url }` - - `"tool_calls"` + The image output from the code interpreter. - - `tool_calls: optional array of ToolCallDelta` + - `type: "image"` - 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 the output. Always `image`. - - `CodeInterpreterToolCallDelta object { index, type, id, code_interpreter }` + - `"image"` - Details of the Code Interpreter tool call the run step was involved in. + - `url: string` - - `index: number` + The URL of the image output from the code interpreter. - The index of the tool call in the tool calls array. + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - - `type: "code_interpreter"` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + - `"in_progress"` - - `"code_interpreter"` + - `"completed"` - - `id: optional string` + - `"incomplete"` - The ID of the tool call. + - `"interpreting"` - - `code_interpreter: optional object { input, outputs }` + - `"failed"` - The Code Interpreter tool call definition. + - `type: "code_interpreter_call"` - - `input: optional string` + The type of the code interpreter tool call. Always `code_interpreter_call`. - The input to the Code Interpreter tool call. + - `"code_interpreter_call"` - - `outputs: optional array of CodeInterpreterLogs or CodeInterpreterOutputImage` + - `agent: optional object { agent_name }` - 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 agent that produced this item. - - `CodeInterpreterLogs object { index, type, logs }` + - `agent_name: string` - Text output from the Code Interpreter tool call as part of a run step. + The canonical name of the agent that produced this item. - - `index: number` + - `LocalShellCall object { id, action, call_id, 3 more }` - The index of the output in the outputs array. + A tool call to run a command on the local shell. - - `type: "logs"` + - `id: string` - Always `logs`. + The unique ID of the local shell call. - - `"logs"` + - `action: object { command, env, type, 3 more }` - - `logs: optional string` + Execute a shell command on the server. - The text output from the Code Interpreter tool call. + - `command: array of string` - - `CodeInterpreterOutputImage object { index, type, image }` + The command to run. - - `index: number` + - `env: map[string]` - The index of the output in the outputs array. + Environment variables to set for the command. - - `type: "image"` + - `type: "exec"` - Always `image`. + The type of the local shell action. Always `exec`. - - `"image"` + - `"exec"` - - `image: optional object { file_id }` + - `timeout_ms: optional number` - - `file_id: optional string` + Optional timeout in milliseconds for the command. - The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. + - `user: optional string` - - `FileSearchToolCallDelta object { file_search, index, type, id }` + Optional user to run the command as. - - `file_search: unknown` + - `working_directory: optional string` - For now, this is always going to be an empty object. + Optional working directory to run the command in. - - `index: number` + - `call_id: string` - The index of the tool call in the tool calls array. + The unique ID of the local shell tool call generated by the model. - - `type: "file_search"` + - `status: "in_progress" or "completed" or "incomplete"` - The type of tool call. This is always going to be `file_search` for this type of tool call. + The status of the local shell call. - - `"file_search"` + - `"in_progress"` - - `id: optional string` + - `"completed"` - The ID of the tool call object. + - `"incomplete"` - - `FunctionToolCallDelta object { index, type, id, function }` + - `type: "local_shell_call"` - - `index: number` + The type of the local shell call. Always `local_shell_call`. - The index of the tool call in the tool calls array. + - `"local_shell_call"` - - `type: "function"` + - `agent: optional object { agent_name }` - The type of tool call. This is always going to be `function` for this type of tool call. + The agent that produced this item. - - `"function"` + - `agent_name: string` - - `id: optional string` + The canonical name of the agent that produced this item. - The ID of the tool call object. + - `LocalShellCallOutput object { id, output, type, 2 more }` - - `function: optional object { arguments, name, output }` + The output of a local shell tool call. - The definition of the function that was called. + - `id: string` - - `arguments: optional string` + The unique ID of the local shell tool call generated by the model. - The arguments passed to the function. + - `output: string` - - `name: optional string` + A JSON string of the output of the local shell tool call. - The name of the function. + - `type: "local_shell_call_output"` - - `output: optional string` + The type of the local shell tool call output. Always `local_shell_call_output`. - The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. + - `"local_shell_call_output"` -### Run Step Delta Event + - `agent: optional object { agent_name }` -- `RunStepDeltaEvent object { id, delta, object }` + The agent that produced this item. - Represents a run step delta i.e. any changed fields on a run step during streaming. + - `agent_name: string` - - `id: string` + The canonical name of the agent that produced this item. - The identifier of the run step, which can be referenced in API endpoints. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `delta: RunStepDelta` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - The delta containing the fields that have changed on the run step. + - `"in_progress"` - - `step_details: optional RunStepDeltaMessageDelta or ToolCallDeltaObject` + - `"completed"` - The details of the run step. + - `"incomplete"` - - `RunStepDeltaMessageDelta object { type, message_creation }` + - `ShellCall object { id, action, call_id, 6 more }` - Details of the message creation by the run step. + A tool call that executes one or more shell commands in a managed environment. - - `type: "message_creation"` + - `id: string` - Always `message_creation`. + The unique ID of the shell tool call. Populated when this item is returned via API. - - `"message_creation"` + - `action: object { commands, max_output_length, timeout_ms }` - - `message_creation: optional object { message_id }` + The shell commands and limits that describe how to run the tool call. - - `message_id: optional string` + - `commands: array of string` - The ID of the message that was created by this run step. + - `max_output_length: number` - - `ToolCallDeltaObject object { type, tool_calls }` + Optional maximum number of characters to return from each command. - Details of the tool call. + - `timeout_ms: number` - - `type: "tool_calls"` + Optional timeout in milliseconds for the commands. - Always `tool_calls`. + - `call_id: string` - - `"tool_calls"` + The unique ID of the shell tool call generated by the model. - - `tool_calls: optional array of ToolCallDelta` + - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` - 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`. + Represents the use of a local environment to perform shell actions. - - `CodeInterpreterToolCallDelta object { index, type, id, code_interpreter }` + - `BetaResponseLocalEnvironment object { type }` - Details of the Code Interpreter tool call the run step was involved in. + Represents the use of a local environment to perform shell actions. - - `index: number` + - `type: "local"` - The index of the tool call in the tool calls array. + The environment type. Always `local`. - - `type: "code_interpreter"` + - `"local"` - The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + - `BetaResponseContainerReference object { container_id, type }` - - `"code_interpreter"` + Represents a container created with /v1/containers. - - `id: optional string` + - `container_id: string` - The ID of the tool call. + - `type: "container_reference"` - - `code_interpreter: optional object { input, outputs }` + The environment type. Always `container_reference`. - The Code Interpreter tool call definition. + - `"container_reference"` - - `input: optional string` + - `status: "in_progress" or "completed" or "incomplete"` - The input to the Code Interpreter tool call. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `outputs: optional array of CodeInterpreterLogs or CodeInterpreterOutputImage` + - `"in_progress"` - 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. + - `"completed"` - - `CodeInterpreterLogs object { index, type, logs }` + - `"incomplete"` - Text output from the Code Interpreter tool call as part of a run step. + - `type: "shell_call"` - - `index: number` + The type of the item. Always `shell_call`. - The index of the output in the outputs array. + - `"shell_call"` - - `type: "logs"` + - `agent: optional object { agent_name }` - Always `logs`. + The agent that produced this item. - - `"logs"` + - `agent_name: string` - - `logs: optional string` + The canonical name of the agent that produced this item. - The text output from the Code Interpreter tool call. + - `caller: optional object { type } or object { caller_id, type }` - - `CodeInterpreterOutputImage object { index, type, image }` + The execution context that produced this tool call. - - `index: number` + - `Direct object { type }` - The index of the output in the outputs array. + - `type: "direct"` - - `type: "image"` + - `"direct"` - Always `image`. + - `Program object { caller_id, type }` - - `"image"` + - `caller_id: string` - - `image: optional object { file_id }` + The call ID of the program item that produced this tool call. - - `file_id: optional string` + - `type: "program"` - The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. + - `"program"` - - `FileSearchToolCallDelta object { file_search, index, type, id }` + - `created_by: optional string` - - `file_search: unknown` + The ID of the entity that created this tool call. - For now, this is always going to be an empty object. + - `ShellCallOutput object { id, call_id, max_output_length, 6 more }` - - `index: number` + The output of a shell tool call that was emitted. - The index of the tool call in the tool calls array. + - `id: string` - - `type: "file_search"` + The unique ID of the shell call output. Populated when this item is returned via API. - The type of tool call. This is always going to be `file_search` for this type of tool call. + - `call_id: string` - - `"file_search"` + The unique ID of the shell tool call generated by the model. - - `id: optional string` + - `max_output_length: number` - The ID of the tool call object. + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - `FunctionToolCallDelta object { index, type, id, function }` + - `output: array of object { outcome, stderr, stdout, created_by }` - - `index: number` + An array of shell call output contents - The index of the tool call in the tool calls array. + - `outcome: object { type } or object { exit_code, type }` - - `type: "function"` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - The type of tool call. This is always going to be `function` for this type of tool call. + - `Timeout object { type }` - - `"function"` + Indicates that the shell call exceeded its configured time limit. - - `id: optional string` + - `type: "timeout"` - The ID of the tool call object. + The outcome type. Always `timeout`. - - `function: optional object { arguments, name, output }` + - `"timeout"` - The definition of the function that was called. + - `Exit object { exit_code, type }` - - `arguments: optional string` + Indicates that the shell commands finished and returned an exit code. - The arguments passed to the function. + - `exit_code: number` - - `name: optional string` + Exit code from the shell process. - The name of the function. + - `type: "exit"` - - `output: optional string` + The outcome type. Always `exit`. - The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. + - `"exit"` - - `object: "thread.run.step.delta"` + - `stderr: string` - The object type, which is always `thread.run.step.delta`. + The standard error output that was captured. - - `"thread.run.step.delta"` + - `stdout: string` -### Run Step Delta Message Delta + The standard output that was captured. -- `RunStepDeltaMessageDelta object { type, message_creation }` + - `created_by: optional string` - Details of the message creation by the run step. + The identifier of the actor that created the item. - - `type: "message_creation"` + - `status: "in_progress" or "completed" or "incomplete"` - Always `message_creation`. + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - `"message_creation"` + - `"in_progress"` - - `message_creation: optional object { message_id }` + - `"completed"` - - `message_id: optional string` + - `"incomplete"` - The ID of the message that was created by this run step. + - `type: "shell_call_output"` -### Run Step Include + The type of the shell call output. Always `shell_call_output`. -- `RunStepInclude = "step_details.tool_calls[*].file_search.results[*].content"` + - `"shell_call_output"` - - `"step_details.tool_calls[*].file_search.results[*].content"` + - `agent: optional object { agent_name }` -### Tool Call + The agent that produced this item. -- `ToolCall = CodeInterpreterToolCall or FileSearchToolCall or FunctionToolCall` + - `agent_name: string` - Details of the Code Interpreter tool call the run step was involved in. + The canonical name of the agent that produced this item. - - `CodeInterpreterToolCall object { id, code_interpreter, type }` + - `caller: optional object { type } or object { caller_id, type }` - Details of the Code Interpreter tool call the run step was involved in. + The execution context that produced this tool call. - - `id: string` + - `Direct object { type }` - The ID of the tool call. + - `type: "direct"` - - `code_interpreter: object { input, outputs }` + - `"direct"` - The Code Interpreter tool call definition. + - `Program object { caller_id, type }` - - `input: string` + - `caller_id: string` - The input to the Code Interpreter tool call. + The call ID of the program item that produced this tool call. - - `outputs: array of object { logs, type } or object { image, type }` + - `type: "program"` - 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. + - `"program"` - - `Logs object { logs, type }` + - `created_by: optional string` - Text output from the Code Interpreter tool call as part of a run step. + The identifier of the actor that created the item. - - `logs: string` + - `ApplyPatchCall object { id, call_id, operation, 5 more }` - The text output from the Code Interpreter tool call. + A tool call that applies file diffs by creating, deleting, or updating files. - - `type: "logs"` + - `id: string` - Always `logs`. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `"logs"` + - `call_id: string` - - `Image object { image, type }` + The unique ID of the apply patch tool call generated by the model. - - `image: object { file_id }` + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - - `file_id: string` + One of the create_file, delete_file, or update_file operations applied via apply_patch. - The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. + - `CreateFile object { diff, path, type }` - - `type: "image"` + Instruction describing how to create a file via the apply_patch tool. - Always `image`. + - `diff: string` - - `"image"` + Diff to apply. - - `type: "code_interpreter"` + - `path: string` - The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + Path of the file to create. - - `"code_interpreter"` + - `type: "create_file"` - - `FileSearchToolCall object { id, file_search, type }` + Create a new file with the provided diff. - - `id: string` + - `"create_file"` - The ID of the tool call object. + - `DeleteFile object { path, type }` - - `file_search: object { ranking_options, results }` + Instruction describing how to delete a file via the apply_patch tool. - For now, this is always going to be an empty object. + - `path: string` - - `ranking_options: optional object { ranker, score_threshold }` + Path of the file to delete. - The ranking options for the file search. + - `type: "delete_file"` - - `ranker: "auto" or "default_2024_08_21"` + Delete the specified file. - The ranker to use for the file search. If not specified will use the `auto` ranker. + - `"delete_file"` - - `"auto"` + - `UpdateFile object { diff, path, type }` - - `"default_2024_08_21"` + Instruction describing how to update a file via the apply_patch tool. - - `score_threshold: number` + - `diff: string` - The score threshold for the file search. All values must be a floating point number between 0 and 1. + Diff to apply. - - `results: optional array of object { file_id, file_name, score, content }` + - `path: string` - The results of the file search. + Path of the file to update. - - `file_id: string` + - `type: "update_file"` - The ID of the file that result was found in. + Update an existing file with the provided diff. - - `file_name: string` + - `"update_file"` - The name of the file that result was found in. + - `status: "in_progress" or "completed"` - - `score: number` + The status of the apply patch tool call. One of `in_progress` or `completed`. - The score of the result. All values must be a floating point number between 0 and 1. + - `"in_progress"` - - `content: optional array of object { text, type }` + - `"completed"` - The content of the result that was found. The content is only included if requested via the include query parameter. + - `type: "apply_patch_call"` - - `text: optional string` + The type of the item. Always `apply_patch_call`. - The text content of the file. + - `"apply_patch_call"` - - `type: optional "text"` + - `agent: optional object { agent_name }` - The type of the content. + The agent that produced this item. - - `"text"` + - `agent_name: string` - - `type: "file_search"` + The canonical name of 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. + - `caller: optional object { type } or object { caller_id, type }` - - `"file_search"` + The execution context that produced this tool call. - - `FunctionToolCall object { id, function, type }` + - `Direct object { type }` - - `id: string` + - `type: "direct"` - The ID of the tool call object. + - `"direct"` - - `function: object { arguments, name, output }` + - `Program object { caller_id, type }` - The definition of the function that was called. + - `caller_id: string` - - `arguments: string` + The call ID of the program item that produced this tool call. - The arguments passed to the function. + - `type: "program"` - - `name: string` + - `"program"` - The name of the function. + - `created_by: optional string` - - `output: string` + The ID of the entity that created this tool call. - The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. + - `ApplyPatchCallOutput object { id, call_id, status, 5 more }` - - `type: "function"` + The output emitted by an apply patch tool call. - The type of tool call. This is always going to be `function` for this type of tool call. + - `id: string` - - `"function"` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. -### Tool Call Delta + - `call_id: string` -- `ToolCallDelta = CodeInterpreterToolCallDelta or FileSearchToolCallDelta or FunctionToolCallDelta` + The unique ID of the apply patch tool call generated by the model. - Details of the Code Interpreter tool call the run step was involved in. + - `status: "completed" or "failed"` - - `CodeInterpreterToolCallDelta object { index, type, id, code_interpreter }` + The status of the apply patch tool call output. One of `completed` or `failed`. - Details of the Code Interpreter tool call the run step was involved in. + - `"completed"` - - `index: number` + - `"failed"` - The index of the tool call in the tool calls array. + - `type: "apply_patch_call_output"` - - `type: "code_interpreter"` + The type of the item. Always `apply_patch_call_output`. - The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + - `"apply_patch_call_output"` - - `"code_interpreter"` + - `agent: optional object { agent_name }` - - `id: optional string` + The agent that produced this item. - The ID of the tool call. + - `agent_name: string` - - `code_interpreter: optional object { input, outputs }` + The canonical name of the agent that produced this item. - The Code Interpreter tool call definition. + - `caller: optional object { type } or object { caller_id, type }` - - `input: optional string` + The execution context that produced this tool call. - The input to the Code Interpreter tool call. + - `Direct object { type }` - - `outputs: optional array of CodeInterpreterLogs or CodeInterpreterOutputImage` + - `type: "direct"` - 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. + - `"direct"` - - `CodeInterpreterLogs object { index, type, logs }` + - `Program object { caller_id, type }` - Text output from the Code Interpreter tool call as part of a run step. + - `caller_id: string` - - `index: number` + The call ID of the program item that produced this tool call. - The index of the output in the outputs array. + - `type: "program"` - - `type: "logs"` + - `"program"` - Always `logs`. + - `created_by: optional string` - - `"logs"` + The ID of the entity that created this tool call output. - - `logs: optional string` + - `output: optional string` - The text output from the Code Interpreter tool call. + Optional textual output returned by the apply patch tool. - - `CodeInterpreterOutputImage object { index, type, image }` + - `McpCall object { id, arguments, name, 7 more }` - - `index: number` + An invocation of a tool on an MCP server. - The index of the output in the outputs array. + - `id: string` - - `type: "image"` + The unique ID of the tool call. - Always `image`. + - `arguments: string` - - `"image"` + A JSON string of the arguments passed to the tool. - - `image: optional object { file_id }` + - `name: string` - - `file_id: optional string` + The name of the tool that was run. - The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. + - `server_label: string` - - `FileSearchToolCallDelta object { file_search, index, type, id }` + The label of the MCP server running the tool. - - `file_search: unknown` + - `type: "mcp_call"` - For now, this is always going to be an empty object. + The type of the item. Always `mcp_call`. - - `index: number` + - `"mcp_call"` - The index of the tool call in the tool calls array. + - `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. - - `id: optional string` + - `approval_request_id: optional string` - The ID of the tool call object. + 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. - - `FunctionToolCallDelta object { index, type, id, function }` + - `error: optional string` - - `index: number` + The error from the tool call, if any. - The index of the tool call in the tool calls array. + - `output: optional string` - - `type: "function"` + The output from the tool call. - The type of tool call. This is always going to be `function` for this type of tool call. + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - - `"function"` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `id: optional string` + - `"in_progress"` - The ID of the tool call object. + - `"completed"` - - `function: optional object { arguments, name, output }` + - `"incomplete"` - The definition of the function that was called. + - `"calling"` - - `arguments: optional string` + - `"failed"` - The arguments passed to the function. + - `McpListTools object { id, server_label, tools, 3 more }` - - `name: optional string` + A list of tools available on an MCP server. - The name of the function. + - `id: string` - - `output: optional string` + The unique ID of the list. - The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. + - `server_label: string` -### Tool Call Delta Object + The label of the MCP server. -- `ToolCallDeltaObject object { type, tool_calls }` + - `tools: array of object { input_schema, name, annotations, description }` - Details of the tool call. + The tools available on the server. - - `type: "tool_calls"` + - `input_schema: unknown` - Always `tool_calls`. + The JSON schema describing the tool's input. - - `"tool_calls"` + - `name: string` - - `tool_calls: optional array of ToolCallDelta` + The name of the tool. - 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: optional unknown` - - `CodeInterpreterToolCallDelta object { index, type, id, code_interpreter }` + Additional annotations about the tool. - Details of the Code Interpreter tool call the run step was involved in. + - `description: optional string` - - `index: number` + The description of the tool. - The index of the tool call in the tool calls array. + - `type: "mcp_list_tools"` - - `type: "code_interpreter"` + The type of the item. Always `mcp_list_tools`. - The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + - `"mcp_list_tools"` - - `"code_interpreter"` + - `agent: optional object { agent_name }` - - `id: optional string` + The agent that produced this item. - The ID of the tool call. + - `agent_name: string` - - `code_interpreter: optional object { input, outputs }` + The canonical name of the agent that produced this item. - The Code Interpreter tool call definition. + - `error: optional string` - - `input: optional string` + Error message if the server could not list tools. - The input to the Code Interpreter tool call. + - `McpApprovalRequest object { id, arguments, name, 3 more }` - - `outputs: optional array of CodeInterpreterLogs or CodeInterpreterOutputImage` + A request for human approval of a tool invocation. - 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. + - `id: string` - - `CodeInterpreterLogs object { index, type, logs }` + The unique ID of the approval request. - Text output from the Code Interpreter tool call as part of a run step. + - `arguments: string` - - `index: number` + A JSON string of arguments for the tool. - The index of the output in the outputs array. + - `name: string` - - `type: "logs"` + The name of the tool to run. - Always `logs`. + - `server_label: string` - - `"logs"` + The label of the MCP server making the request. - - `logs: optional string` + - `type: "mcp_approval_request"` - The text output from the Code Interpreter tool call. + The type of the item. Always `mcp_approval_request`. - - `CodeInterpreterOutputImage object { index, type, image }` + - `"mcp_approval_request"` - - `index: number` + - `agent: optional object { agent_name }` - The index of the output in the outputs array. + The agent that produced this item. - - `type: "image"` + - `agent_name: string` - Always `image`. + The canonical name of the agent that produced this item. - - `"image"` + - `McpApprovalResponse object { id, approval_request_id, approve, 3 more }` - - `image: optional object { file_id }` + A response to an MCP approval request. - - `file_id: optional string` + - `id: string` - The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. + The unique ID of the approval response - - `FileSearchToolCallDelta object { file_search, index, type, id }` + - `approval_request_id: string` - - `file_search: unknown` + The ID of the approval request being answered. - For now, this is always going to be an empty object. + - `approve: boolean` - - `index: number` + Whether the request was approved. - The index of the tool call in the tool calls array. + - `type: "mcp_approval_response"` - - `type: "file_search"` + The type of the item. Always `mcp_approval_response`. - The type of tool call. This is always going to be `file_search` for this type of tool call. + - `"mcp_approval_response"` - - `"file_search"` + - `agent: optional object { agent_name }` - - `id: optional string` + The agent that produced this item. - The ID of the tool call object. + - `agent_name: string` - - `FunctionToolCallDelta object { index, type, id, function }` + The canonical name of the agent that produced this item. - - `index: number` + - `reason: optional string` - The index of the tool call in the tool calls array. + Optional reason for the decision. - - `type: "function"` + - `CustomToolCall object { call_id, input, name, 5 more }` - The type of tool call. This is always going to be `function` for this type of tool call. + A call to a custom tool created by the model. - - `"function"` + - `call_id: string` - - `id: optional string` + An identifier used to map this custom tool call to a tool call output. - The ID of the tool call object. + - `input: string` - - `function: optional object { arguments, name, output }` + The input for the custom tool call generated by the model. - The definition of the function that was called. + - `name: string` - - `arguments: optional string` + The name of the custom tool being called. - The arguments passed to the function. + - `type: "custom_tool_call"` - - `name: optional string` + The type of the custom tool call. Always `custom_tool_call`. - The name of the function. + - `"custom_tool_call"` - - `output: optional string` + - `id: optional string` - The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. + The unique ID of the custom tool call in the OpenAI platform. -### Tool Calls Step Details + - `agent: optional object { agent_name }` -- `ToolCallsStepDetails object { tool_calls, type }` + The agent that produced this item. - Details of the tool call. + - `agent_name: string` - - `tool_calls: array of ToolCall` + The canonical name of the agent that produced this item. - 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`. + - `caller: optional object { type } or object { caller_id, type }` - - `CodeInterpreterToolCall object { id, code_interpreter, type }` + The execution context that produced this tool call. - Details of the Code Interpreter tool call the run step was involved in. + - `Direct object { type }` - - `id: string` + - `type: "direct"` - The ID of the tool call. + - `"direct"` - - `code_interpreter: object { input, outputs }` + - `Program object { caller_id, type }` - The Code Interpreter tool call definition. + - `caller_id: string` - - `input: string` + The call ID of the program item that produced this tool call. - The input to the Code Interpreter tool call. + - `type: "program"` - - `outputs: array of object { logs, type } or object { image, type }` + - `"program"` - 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. + - `namespace: optional string` - - `Logs object { logs, type }` + The namespace of the custom tool being called. - Text output from the Code Interpreter tool call as part of a run step. + - `CustomToolCallOutput object { id, call_id, output, 5 more }` - - `logs: string` + - `id: string` - The text output from the Code Interpreter tool call. + The unique ID of the custom tool call output item. - - `type: "logs"` + - `call_id: string` - Always `logs`. + The call ID, used to map this custom tool call output to a custom tool call. - - `"logs"` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `Image object { image, type }` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `image: object { file_id }` + - `StringOutput = string` - - `file_id: string` + A string of the output of the custom tool call. - The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `type: "image"` + Text, image, or file output of the custom tool call. - Always `image`. + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `"image"` + A text input to the model. - - `type: "code_interpreter"` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `"code_interpreter"` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `FileSearchToolCall object { id, file_search, type }` + A file input to the model. - - `id: string` + - `status: "in_progress" or "completed" or "incomplete"` - The ID of the tool call object. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `file_search: object { ranking_options, results }` + - `"in_progress"` - For now, this is always going to be an empty object. + - `"completed"` - - `ranking_options: optional object { ranker, score_threshold }` + - `"incomplete"` - The ranking options for the file search. + - `type: "custom_tool_call_output"` - - `ranker: "auto" or "default_2024_08_21"` + The type of the custom tool call output. Always `custom_tool_call_output`. - The ranker to use for the file search. If not specified will use the `auto` ranker. + - `"custom_tool_call_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 }` + - `caller: optional object { type } or object { caller_id, type }` - The results of the file search. + The execution context that produced this tool call. - - `file_id: string` + - `Direct object { type }` - The ID of the file that result was found in. + - `type: "direct"` - - `file_name: string` + The caller type. Always `direct`. - The name of the file that result was found in. + - `"direct"` - - `score: number` + - `Program object { caller_id, type }` - The score of the result. All values must be a floating point number between 0 and 1. + - `caller_id: string` - - `content: optional array of object { text, type }` + The call ID of the program item that produced this tool call. - The content of the result that was found. The content is only included if requested via the include query parameter. + - `type: "program"` - - `text: optional string` + The caller type. Always `program`. - The text content of the file. + - `"program"` - - `type: optional "text"` + - `created_by: optional string` - The type of the content. + The identifier of the actor that created the item. - - `"text"` + - `parallel_tool_calls: boolean` - - `type: "file_search"` + Whether to allow the model to run tool calls in parallel. - The type of tool call. This is always going to be `file_search` for this type of tool call. + - `temperature: number` - - `"file_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. - - `FunctionToolCall object { id, function, type }` + - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` - - `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 ID of the tool call object. + - `BetaToolChoiceOptions = "none" or "auto" or "required"` - - `function: object { arguments, name, output }` + Controls which (if any) tool is called by the model. - The definition of the function that was called. + `none` means the model will not call any tool and instead generates a message. - - `arguments: string` + `auto` means the model can pick between generating a message or calling one or + more tools. - The arguments passed to the function. + `required` means the model must call one or more tools. - - `name: string` + - `"none"` - The name of the function. + - `"auto"` - - `output: string` + - `"required"` - The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. + - `BetaToolChoiceAllowed object { mode, tools, type }` - - `type: "function"` + Constrains the tools available to the model to a pre-defined set. - The type of tool call. This is always going to be `function` for this type of tool call. + - `mode: "auto" or "required"` - - `"function"` + Constrains the tools available to the model to a pre-defined set. - - `type: "tool_calls"` + `auto` allows the model to pick from among the allowed tools and generate a + message. - Always `tool_calls`. + `required` requires the model to call one or more of the allowed tools. - - `"tool_calls"` + - `"auto"` -# Messages + - `"required"` -## List messages + - `tools: array of map[unknown]` -**get** `/threads/{thread_id}/messages` + A list of tool definitions that the model should be allowed to call. -List messages + For the Responses API, the list of tool definitions might look like: -### Path Parameters + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` -- `thread_id: string` + - `type: "allowed_tools"` -### Query Parameters + Allowed tool configuration type. Always `allowed_tools`. -- `after: optional string` + - `"allowed_tools"` - 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. + - `BetaToolChoiceTypes object { type }` -- `before: optional string` + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](/docs/guides/tools). - 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. + - `type: "file_search" or "web_search_preview" or "computer" or 5 more` -- `limit: optional number` + The type of hosted tool the model should to use. Learn more about + [built-in tools](/docs/guides/tools). - A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. + Allowed values are: -- `order: optional "asc" or "desc"` + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. + - `"file_search"` - - `"asc"` + - `"web_search_preview"` - - `"desc"` + - `"computer"` -- `run_id: optional string` + - `"computer_use_preview"` - Filter messages by the run ID that generated them. + - `"computer_use"` -### Returns + - `"web_search_preview_2025_03_11"` -- `data: array of Message` + - `"image_generation"` - - `id: string` + - `"code_interpreter"` - The identifier, which can be referenced in API endpoints. + - `BetaToolChoiceFunction object { name, type }` - - `assistant_id: string` + Use this option to force the model to call a specific function. - If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. + - `name: string` - - `attachments: array of object { file_id, tools }` + The name of the function to call. - A list of files attached to the message, and the tools they were added to. + - `type: "function"` - - `file_id: optional string` + For function calling, the type is always `function`. - The ID of the file to attach to the message. + - `"function"` - - `tools: optional array of CodeInterpreterTool or object { type }` + - `BetaToolChoiceMcp object { server_label, type, name }` - The tools to add this file to. + Use this option to force the model to call a specific tool on a remote MCP server. - - `CodeInterpreterTool object { type }` + - `server_label: string` - - `type: "code_interpreter"` + The label of the MCP server to use. - The type of tool being defined: `code_interpreter` + - `type: "mcp"` - - `"code_interpreter"` + For MCP tools, the type is always `mcp`. - - `AssistantToolsFileSearchTypeOnly object { type }` + - `"mcp"` - - `type: "file_search"` + - `name: optional string` - The type of tool being defined: `file_search` + The name of the tool to call on the server. - - `"file_search"` + - `BetaToolChoiceCustom object { name, type }` - - `completed_at: number` + Use this option to force the model to call a specific custom tool. - The Unix timestamp (in seconds) for when the message was completed. + - `name: string` - - `content: array of MessageContent` + The name of the custom tool to call. - The content of the message in array of text and/or images. + - `type: "custom"` - - `ImageFileContentBlock object { image_file, type }` + For custom tool calling, the type is always `custom`. - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + - `"custom"` - - `image_file: ImageFile` + - `BetaSpecificProgrammaticToolCallingParam object { type }` - - `file_id: string` + - `type: "programmatic_tool_calling"` - The [File](https://platform.openai.com/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 tool to call. Always `programmatic_tool_calling`. - - `detail: optional "auto" or "low" or "high"` + - `"programmatic_tool_calling"` - 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`. + - `BetaToolChoiceApplyPatch object { type }` - - `"auto"` + Forces the model to call the apply_patch tool when executing a tool call. - - `"low"` + - `type: "apply_patch"` - - `"high"` + The tool to call. Always `apply_patch`. - - `type: "image_file"` + - `"apply_patch"` - Always `image_file`. + - `BetaToolChoiceShell object { type }` - - `"image_file"` + Forces the model to call the shell tool when a tool call is required. - - `ImageURLContentBlock object { image_url, type }` + - `type: "shell"` - References an image URL in the content of a message. + The tool to call. Always `shell`. - - `image_url: ImageURL` + - `"shell"` - - `url: 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 external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + 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. - - `detail: optional "auto" or "low" or "high"` + We support the following categories of tools: - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](/docs/guides/tools-web-search) + or [file search](/docs/guides/tools-file-search). Learn more about + [built-in tools](/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](/docs/guides/function-calling). You can also use + custom tools to call your own code. - - `"auto"` + - `Function object { name, parameters, strict, 5 more }` - - `"low"` + 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). - - `"high"` + - `name: string` - - `type: "image_url"` + The name of the function to call. - The type of the content part. + - `parameters: map[unknown]` - - `"image_url"` + A JSON schema object describing the parameters of the function. - - `TextContentBlock object { text, type }` + - `strict: boolean` - The text content that is part of a message. + Whether strict parameter validation is enforced for this function tool. - - `text: Text` + - `type: "function"` - - `annotations: array of Annotation` + The type of the function tool. Always `function`. - - `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` + - `"function"` - 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. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `end_index: number` + The tool invocation context(s). - - `file_citation: object { file_id }` + - `"direct"` - - `file_id: string` + - `"programmatic"` - The ID of the specific File the citation is from. + - `defer_loading: optional boolean` - - `start_index: number` + Whether this function is deferred and loaded via tool search. - - `text: string` + - `description: optional string` - The text in the message content that needs to be replaced. + A description of the function. Used by the model to determine whether or not to call the function. - - `type: "file_citation"` + - `output_schema: optional map[unknown]` - Always `file_citation`. + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `"file_citation"` + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - - `FilePathAnnotation object { end_index, file_path, start_index, 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). - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + - `type: "file_search"` - - `end_index: number` + The type of the file search tool. Always `file_search`. - - `file_path: object { file_id }` + - `"file_search"` - - `file_id: string` + - `vector_store_ids: array of string` - The ID of the file that was generated. + The IDs of the vector stores to search. - - `start_index: number` + - `filters: optional object { key, type, value } or object { filters, type }` - - `text: string` + A filter to apply. - The text in the message content that needs to be replaced. + - `ComparisonFilter object { key, type, value }` - - `type: "file_path"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - Always `file_path`. + - `key: string` - - `"file_path"` + The key to compare against the value. - - `value: string` + - `type: "eq" or "ne" or "gt" or 5 more` - The data that makes up the text. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `type: "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 - Always `text`. + - `"eq"` - - `"text"` + - `"ne"` - - `RefusalContentBlock object { refusal, type }` + - `"gt"` - The refusal content generated by the assistant. + - `"gte"` - - `refusal: string` + - `"lt"` - - `type: "refusal"` + - `"lte"` - Always `refusal`. + - `"in"` - - `"refusal"` + - `"nin"` - - `created_at: number` + - `value: string or number or boolean or array of string or number` - The Unix timestamp (in seconds) for when the message was created. + The value to compare against the attribute key; supports string, number, or boolean types. - - `incomplete_at: number` + - `string` - The Unix timestamp (in seconds) for when the message was marked as incomplete. + - `number` - - `incomplete_details: object { reason }` + - `boolean` - On an incomplete message, details about why the message is incomplete. + - `array of string or number` - - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` + - `string` - The reason the message is incomplete. + - `number` - - `"content_filter"` + - `CompoundFilter object { filters, type }` - - `"max_tokens"` + Combine multiple filters using `and` or `or`. - - `"run_cancelled"` + - `filters: array of object { key, type, value } or unknown` - - `"run_expired"` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `"run_failed"` + - `ComparisonFilter object { key, type, value }` - - `metadata: Metadata` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - 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. + - `key: string` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The key to compare against the value. - - `object: "thread.message"` + - `type: "eq" or "ne" or "gt" or 5 more` - The object type, which is always `thread.message`. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `"thread.message"` + - `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 - - `role: "user" or "assistant"` + - `"eq"` - The entity that produced the message. One of `user` or `assistant`. + - `"ne"` - - `"user"` + - `"gt"` - - `"assistant"` + - `"gte"` - - `run_id: string` + - `"lt"` - The ID of the [run](https://platform.openai.com/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. + - `"lte"` - - `status: "in_progress" or "incomplete" or "completed"` + - `"in"` - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + - `"nin"` - - `"in_progress"` + - `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. - - `"completed"` + - `string` - - `thread_id: string` + - `number` - The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + - `boolean` -- `first_id: string` + - `array of string or number` -- `has_more: boolean` + - `string` -- `last_id: string` + - `number` -- `object: string` + - `unknown` -### Example + - `type: "and" or "or"` -```http -curl https://api.openai.com/v1/threads/$THREAD_ID/messages \ - -H 'OpenAI-Beta: assistants=v2' \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + Type of operation: `and` or `or`. -#### Response + - `"and"` -```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" -} -``` + - `"or"` -### Example + - `max_num_results: optional number` -```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" -``` + The maximum number of results to return. This number should be between 1 and 50 inclusive. -#### Response + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` -```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 -} -``` + Ranking options for search. -## Create message + - `hybrid_search: optional object { embedding_weight, text_weight }` -**post** `/threads/{thread_id}/messages` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. -Create message + - `embedding_weight: number` -### Path Parameters + The weight of the embedding in the reciprocal ranking fusion. -- `thread_id: string` + - `text_weight: number` -### Body Parameters + The weight of the text in the reciprocal ranking fusion. -- `content: string or array of MessageContentPartParam` + - `ranker: optional "auto" or "default-2024-11-15"` - The text contents of the message. + The ranker to use for the file search. - - `TextContent = string` + - `"auto"` - The text contents of the message. + - `"default-2024-11-15"` - - `ArrayOfContentParts = array of MessageContentPartParam` + - `score_threshold: optional 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](https://platform.openai.com/docs/models). + 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. - - `ImageFileContentBlock object { image_file, type }` + - `Computer object { type }` - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `image_file: ImageFile` + - `type: "computer"` - - `file_id: string` + The type of the computer tool. Always `computer`. - The [File](https://platform.openai.com/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. + - `"computer"` - - `detail: optional "auto" or "low" or "high"` + - `ComputerUsePreview object { display_height, display_width, environment, 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`. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"auto"` + - `display_height: number` - - `"low"` + The height of the computer display. - - `"high"` + - `display_width: number` - - `type: "image_file"` + The width of the computer display. - Always `image_file`. + - `environment: "windows" or "mac" or "linux" or 2 more` - - `"image_file"` + The type of computer environment to control. - - `ImageURLContentBlock object { image_url, type }` + - `"windows"` - References an image URL in the content of a message. + - `"mac"` - - `image_url: ImageURL` + - `"linux"` - - `url: string` + - `"ubuntu"` - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `"browser"` - - `detail: optional "auto" or "low" or "high"` + - `type: "computer_use_preview"` - 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 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). - - `type: "image_url"` + - `type: "web_search" or "web_search_2025_08_26"` - The type of the content part. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `"image_url"` + - `"web_search"` - - `TextContentBlockParam object { text, type }` + - `"web_search_2025_08_26"` - The text content that is part of a message. + - `filters: optional object { allowed_domains }` - - `text: string` + Filters for the search. - Text content to be sent to the model + - `allowed_domains: optional array of string` - - `type: "text"` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - Always `text`. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `"text"` + - `search_context_size: optional "low" or "medium" or "high"` -- `role: "user" or "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. - The role of the entity that is creating the message. Allowed values include: + - `"low"` - - `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. + - `"medium"` - - `"user"` + - `"high"` - - `"assistant"` + - `user_location: optional object { city, country, region, 2 more }` -- `attachments: optional array of object { file_id, tools }` + The approximate location of the user. - A list of files attached to the message, and the tools they should be added to. + - `city: optional string` - - `file_id: optional string` + Free text input for the city of the user, e.g. `San Francisco`. - The ID of the file to attach to the message. + - `country: optional string` - - `tools: optional array of CodeInterpreterTool or object { type }` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The tools to add this file to. + - `region: optional string` - - `CodeInterpreterTool object { type }` + Free text input for the region of the user, e.g. `California`. - - `type: "code_interpreter"` + - `timezone: optional string` - The type of tool being defined: `code_interpreter` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `"code_interpreter"` + - `type: optional "approximate"` - - `FileSearch object { type }` + The type of location approximation. Always `approximate`. - - `type: "file_search"` + - `"approximate"` - The type of tool being defined: `file_search` + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `"file_search"` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). -- `metadata: optional Metadata` + - `server_label: 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. + A label for this MCP server, used to identify it in tool calls. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `type: "mcp"` -### Returns + The type of the MCP tool. Always `mcp`. -- `Message object { id, assistant_id, attachments, 11 more }` + - `"mcp"` - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + - `allowed_callers: optional array of "direct" or "programmatic"` - - `id: string` + The tool invocation context(s). - The identifier, which can be referenced in API endpoints. + - `"direct"` - - `assistant_id: string` + - `"programmatic"` - If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `attachments: array of object { file_id, tools }` + List of allowed tool names or a filter object. - A list of files attached to the message, and the tools they were added to. + - `McpAllowedTools = array of string` - - `file_id: optional string` + A string array of allowed tool names - The ID of the file to attach to the message. + - `McpToolFilter object { read_only, tool_names }` - - `tools: optional array of CodeInterpreterTool or object { type }` + A filter object to specify which tools are allowed. - The tools to add this file to. + - `read_only: optional boolean` - - `CodeInterpreterTool object { type }` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `type: "code_interpreter"` + - `tool_names: optional array of string` - The type of tool being defined: `code_interpreter` + List of allowed tool names. - - `"code_interpreter"` + - `authorization: optional string` - - `AssistantToolsFileSearchTypeOnly object { 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. - - `type: "file_search"` + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - The type of tool being defined: `file_search` + 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_search"` + Currently supported `connector_id` values are: - - `completed_at: 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 Unix timestamp (in seconds) for when the message was completed. + - `"connector_dropbox"` - - `content: array of MessageContent` + - `"connector_gmail"` - The content of the message in array of text and/or images. + - `"connector_googlecalendar"` - - `ImageFileContentBlock object { image_file, type }` + - `"connector_googledrive"` - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + - `"connector_microsoftteams"` - - `image_file: ImageFile` + - `"connector_outlookcalendar"` - - `file_id: string` + - `"connector_outlookemail"` - The [File](https://platform.openai.com/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. + - `"connector_sharepoint"` - - `detail: optional "auto" or "low" or "high"` + - `defer_loading: optional boolean` - 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`. + Whether this MCP tool is deferred and discovered via tool search. - - `"auto"` + - `headers: optional map[string]` - - `"low"` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `"high"` + - `require_approval: optional object { always, never } or "always" or "never"` - - `type: "image_file"` + Specify which of the MCP server's tools require approval. - Always `image_file`. + - `McpToolApprovalFilter object { always, never }` - - `"image_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. - - `ImageURLContentBlock object { image_url, type }` + - `always: optional object { read_only, tool_names }` - References an image URL in the content of a message. + A filter object to specify which tools are allowed. - - `image_url: ImageURL` + - `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 external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `tool_names: optional array of string` - - `detail: optional "auto" or "low" or "high"` + List of allowed tool names. - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + - `never: optional object { read_only, tool_names }` - - `"auto"` + A filter object to specify which tools are allowed. - - `"low"` + - `read_only: optional boolean` - - `"high"` + 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: "image_url"` + - `tool_names: optional array of string` - The type of the content part. + List of allowed tool names. - - `"image_url"` + - `McpToolApprovalSetting = "always" or "never"` - - `TextContentBlock object { text, 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. - The text content that is part of a message. + - `"always"` - - `text: Text` + - `"never"` - - `annotations: array of Annotation` + - `server_description: optional string` - - `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` + Optional description of the MCP server, used to provide more context. - 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. + - `server_url: optional string` - - `end_index: number` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `file_citation: object { file_id }` + - `tunnel_id: optional string` - - `file_id: 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 ID of the specific File the citation is from. + - `CodeInterpreter object { container, type, allowed_callers }` - - `start_index: number` + A tool that runs Python code to help generate a response to a prompt. - - `text: string` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - The text in the message content that needs to be replaced. + 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: "file_citation"` + - `string` - Always `file_citation`. + The container ID. - - `"file_citation"` + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - - `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + - `type: "auto"` - - `end_index: number` + Always `auto`. - - `file_path: object { file_id }` + - `"auto"` - - `file_id: string` + - `file_ids: optional array of string` - The ID of the file that was generated. + 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"` - - `text: string` + The memory limit for the code interpreter container. - The text in the message content that needs to be replaced. + - `"1g"` - - `type: "file_path"` + - `"4g"` - Always `file_path`. + - `"16g"` - - `"file_path"` + - `"64g"` - - `value: string` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - The data that makes up the text. + Network access policy for the container. - - `type: "text"` + - `BetaContainerNetworkPolicyDisabled object { type }` - Always `text`. + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `"text"` + - `type: "code_interpreter"` - - `RefusalContentBlock object { refusal, type }` + The type of the code interpreter tool. Always `code_interpreter`. - The refusal content generated by the assistant. + - `"code_interpreter"` - - `refusal: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `type: "refusal"` + The tool invocation context(s). - Always `refusal`. + - `"direct"` - - `"refusal"` + - `"programmatic"` - - `created_at: number` + - `ProgrammaticToolCalling object { type }` - The Unix timestamp (in seconds) for when the message was created. + - `type: "programmatic_tool_calling"` - - `incomplete_at: number` + The type of the tool. Always `programmatic_tool_calling`. - The Unix timestamp (in seconds) for when the message was marked as incomplete. + - `"programmatic_tool_calling"` - - `incomplete_details: object { reason }` + - `ImageGeneration object { type, action, background, 9 more }` - On an incomplete message, details about why the message is incomplete. + A tool that generates images using the GPT image models. - - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` + - `type: "image_generation"` - The reason the message is incomplete. + The type of the image generation tool. Always `image_generation`. - - `"content_filter"` + - `"image_generation"` - - `"max_tokens"` + - `action: optional "generate" or "edit" or "auto"` - - `"run_cancelled"` + Whether to generate a new image or edit an existing image. Default: `auto`. - - `"run_expired"` + - `"generate"` - - `"run_failed"` + - `"edit"` - - `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. + - `background: optional "transparent" or "opaque" or "auto"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - - `object: "thread.message"` + - `"transparent"` - The object type, which is always `thread.message`. + - `"opaque"` - - `"thread.message"` + - `"auto"` - - `role: "user" or "assistant"` + - `input_fidelity: optional "high" or "low"` - The entity that produced the message. One of `user` or `assistant`. + 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`. - - `"user"` + - `"high"` - - `"assistant"` + - `"low"` - - `run_id: string` + - `input_image_mask: optional object { file_id, image_url }` - The ID of the [run](https://platform.openai.com/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. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `status: "in_progress" or "incomplete" or "completed"` + - `file_id: optional string` - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + File ID for the mask image. - - `"in_progress"` + - `image_url: optional string` - - `"incomplete"` + Base64-encoded mask image. - - `"completed"` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `thread_id: string` + The image generation model to use. Default: `gpt-image-1`. - The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + - `string` -### Example + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` -```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" - }' -``` + The image generation model to use. Default: `gpt-image-1`. -#### Response + - `"gpt-image-1"` -```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" -} -``` + - `"gpt-image-1-mini"` -### Example + - `"gpt-image-1.5"` -```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." - }' -``` + - `moderation: optional "auto" or "low"` -#### Response + Moderation level for the generated image. Default: `auto`. -```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": {} -} -``` + - `"auto"` -## Modify message + - `"low"` -**post** `/threads/{thread_id}/messages/{message_id}` + - `output_compression: optional number` -Modify message + Compression level for the output image. Default: 100. -### Path Parameters + - `output_format: optional "png" or "webp" or "jpeg"` -- `thread_id: string` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. -- `message_id: string` + - `"png"` -### Body Parameters + - `"webp"` -- `metadata: optional Metadata` + - `"jpeg"` - 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. + - `partial_images: optional number` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. -### Returns + - `quality: optional "low" or "medium" or "high" or "auto"` -- `Message object { id, assistant_id, attachments, 11 more }` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + - `"low"` - - `id: string` + - `"medium"` - The identifier, which can be referenced in API endpoints. + - `"high"` - - `assistant_id: string` + - `"auto"` - If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `attachments: array of object { file_id, 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`. - A list of files attached to the message, and the tools they were added to. + - `string` - - `file_id: optional string` + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - The ID of the file to attach to the 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`. - - `tools: optional array of CodeInterpreterTool or object { type }` + - `"1024x1024"` - The tools to add this file to. + - `"1024x1536"` - - `CodeInterpreterTool object { type }` + - `"1536x1024"` - - `type: "code_interpreter"` + - `"auto"` - The type of tool being defined: `code_interpreter` + - `LocalShell object { type }` - - `"code_interpreter"` + A tool that allows the model to execute shell commands in a local environment. - - `AssistantToolsFileSearchTypeOnly object { type }` + - `type: "local_shell"` - - `type: "file_search"` + The type of the local shell tool. Always `local_shell`. - The type of tool being defined: `file_search` + - `"local_shell"` - - `"file_search"` + - `Shell object { type, allowed_callers, environment }` - - `completed_at: number` + A tool that allows the model to execute shell commands. - The Unix timestamp (in seconds) for when the message was completed. + - `type: "shell"` - - `content: array of MessageContent` + The type of the shell tool. Always `shell`. - The content of the message in array of text and/or images. + - `"shell"` - - `ImageFileContentBlock object { image_file, type }` + - `allowed_callers: optional array of "direct" or "programmatic"` - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + The tool invocation context(s). - - `image_file: ImageFile` + - `"direct"` - - `file_id: string` + - `"programmatic"` - The [File](https://platform.openai.com/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. + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - `detail: optional "auto" or "low" or "high"` + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 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`. + - `BetaLocalEnvironment object { type, skills }` - - `"auto"` + - `BetaContainerReference object { container_id, type }` - - `"low"` + - `Custom object { name, type, allowed_callers, 3 more }` - - `"high"` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `type: "image_file"` + - `name: string` - Always `image_file`. + The name of the custom tool, used to identify it in tool calls. - - `"image_file"` + - `type: "custom"` - - `ImageURLContentBlock object { image_url, type }` + The type of the custom tool. Always `custom`. - References an image URL in the content of a message. + - `"custom"` - - `image_url: ImageURL` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `url: string` + The tool invocation context(s). - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `"direct"` - - `detail: optional "auto" or "low" or "high"` + - `"programmatic"` - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + - `defer_loading: optional boolean` - - `"auto"` + Whether this tool should be deferred and discovered via tool search. - - `"low"` + - `description: optional string` - - `"high"` + Optional description of the custom tool, used to provide more context. - - `type: "image_url"` + - `format: optional object { type } or object { definition, syntax, type }` - The type of the content part. + The input format for the custom tool. Default is unconstrained text. - - `"image_url"` + - `Text object { type }` - - `TextContentBlock object { text, type }` + Unconstrained free-form text. - The text content that is part of a message. + - `type: "text"` - - `text: Text` + Unconstrained text format. Always `text`. - - `annotations: array of Annotation` + - `"text"` - - `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` + - `Grammar object { definition, syntax, 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. + A grammar defined by the user. - - `end_index: number` + - `definition: string` - - `file_citation: object { file_id }` + The grammar definition. - - `file_id: string` + - `syntax: "lark" or "regex"` - The ID of the specific File the citation is from. + The syntax of the grammar definition. One of `lark` or `regex`. - - `start_index: number` + - `"lark"` - - `text: string` + - `"regex"` - The text in the message content that needs to be replaced. + - `type: "grammar"` - - `type: "file_citation"` + Grammar format. Always `grammar`. - Always `file_citation`. + - `"grammar"` - - `"file_citation"` + - `Namespace object { description, name, tools, type }` - - `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` + Groups function/custom tools under a shared namespace. - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + - `description: string` - - `end_index: number` + A description of the namespace shown to the model. - - `file_path: object { file_id }` + - `name: string` - - `file_id: string` + The namespace name used in tool calls (for example, `crm`). - The ID of the file that was generated. + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - - `start_index: number` + The function/custom tools available inside this namespace. - - `text: string` + - `Function object { name, type, allowed_callers, 5 more }` - The text in the message content that needs to be replaced. + - `name: string` - - `type: "file_path"` + - `type: "function"` - Always `file_path`. + - `"function"` - - `"file_path"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `value: string` + The tool invocation context(s). - The data that makes up the text. + - `"direct"` - - `type: "text"` + - `"programmatic"` - Always `text`. + - `defer_loading: optional boolean` - - `"text"` + Whether this function should be deferred and discovered via tool search. - - `RefusalContentBlock object { refusal, type }` + - `description: optional string` - The refusal content generated by the assistant. + - `output_schema: optional map[unknown]` - - `refusal: string` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `type: "refusal"` + - `parameters: optional unknown` - Always `refusal`. + - `strict: optional boolean` - - `"refusal"` + 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. - - `created_at: number` + - `Custom object { name, type, allowed_callers, 3 more }` - The Unix timestamp (in seconds) for when the message was created. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `incomplete_at: number` + - `name: string` - The Unix timestamp (in seconds) for when the message was marked as incomplete. + The name of the custom tool, used to identify it in tool calls. - - `incomplete_details: object { reason }` + - `type: "custom"` - On an incomplete message, details about why the message is incomplete. + The type of the custom tool. Always `custom`. - - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` + - `"custom"` - The reason the message is incomplete. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"content_filter"` + The tool invocation context(s). - - `"max_tokens"` + - `"direct"` - - `"run_cancelled"` + - `"programmatic"` - - `"run_expired"` + - `defer_loading: optional boolean` - - `"run_failed"` + Whether this tool should be deferred and discovered via tool search. - - `metadata: Metadata` + - `description: 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. + Optional description of the custom tool, used to provide more context. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `format: optional object { type } or object { definition, syntax, type }` - - `object: "thread.message"` + The input format for the custom tool. Default is unconstrained text. - The object type, which is always `thread.message`. + - `Text object { type }` - - `"thread.message"` + Unconstrained free-form text. - - `role: "user" or "assistant"` + - `type: "text"` - The entity that produced the message. One of `user` or `assistant`. + Unconstrained text format. Always `text`. - - `"user"` + - `"text"` - - `"assistant"` + - `Grammar object { definition, syntax, type }` - - `run_id: string` + A grammar defined by the user. - The ID of the [run](https://platform.openai.com/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. + - `definition: string` - - `status: "in_progress" or "incomplete" or "completed"` + The grammar definition. - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + - `syntax: "lark" or "regex"` - - `"in_progress"` + The syntax of the grammar definition. One of `lark` or `regex`. - - `"incomplete"` + - `"lark"` - - `"completed"` + - `"regex"` - - `thread_id: string` + - `type: "grammar"` - The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + Grammar format. Always `grammar`. -### Example + - `"grammar"` -```http -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 '{}' -``` + - `type: "namespace"` -#### Response + The type of the tool. Always `namespace`. -```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" -} -``` + - `"namespace"` -### Example + - `ToolSearch object { type, description, execution, parameters }` -```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" \ - -d '{ - "metadata": { - "modified": "true", - "user": "abc123" - } - }' -``` + Hosted or BYOT tool search configuration for deferred tools. -#### Response + - `type: "tool_search"` -```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": [] - } - } - ], - "file_ids": [], - "metadata": { - "modified": "true", - "user": "abc123" - } -} -``` + The type of the tool. Always `tool_search`. -## Retrieve message + - `"tool_search"` -**get** `/threads/{thread_id}/messages/{message_id}` + - `description: optional string` -Retrieve message + Description shown to the model for a client-executed tool search tool. -### Path Parameters + - `execution: optional "server" or "client"` -- `thread_id: string` + Whether tool search is executed by the server or by the client. -- `message_id: string` + - `"server"` -### Returns + - `"client"` -- `Message object { id, assistant_id, attachments, 11 more }` + - `parameters: optional unknown` - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + Parameter schema for a client-executed tool search tool. - - `id: string` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - The identifier, which can be referenced in API endpoints. + 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). - - `assistant_id: string` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `attachments: array of object { file_id, tools }` + - `"web_search_preview"` - A list of files attached to the message, and the tools they were added to. + - `"web_search_preview_2025_03_11"` - - `file_id: optional string` + - `search_content_types: optional array of "text" or "image"` - The ID of the file to attach to the message. + - `"text"` - - `tools: optional array of CodeInterpreterTool or object { type }` + - `"image"` - The tools to add this file to. + - `search_context_size: optional "low" or "medium" or "high"` - - `CodeInterpreterTool 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: "code_interpreter"` + - `"low"` - The type of tool being defined: `code_interpreter` + - `"medium"` - - `"code_interpreter"` + - `"high"` - - `AssistantToolsFileSearchTypeOnly object { type }` + - `user_location: optional object { type, city, country, 2 more }` - - `type: "file_search"` + The user's location. - The type of tool being defined: `file_search` + - `type: "approximate"` - - `"file_search"` + The type of location approximation. Always `approximate`. - - `completed_at: number` + - `"approximate"` - The Unix timestamp (in seconds) for when the message was completed. + - `city: optional string` - - `content: array of MessageContent` + Free text input for the city of the user, e.g. `San Francisco`. - The content of the message in array of text and/or images. + - `country: optional string` - - `ImageFileContentBlock object { image_file, type }` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + - `region: optional string` - - `image_file: ImageFile` + Free text input for the region of the user, e.g. `California`. - - `file_id: string` + - `timezone: optional string` - The [File](https://platform.openai.com/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 [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `detail: optional "auto" or "low" or "high"` + - `ApplyPatch object { type, allowed_callers }` - 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`. + Allows the assistant to create, delete, or update files using unified diffs. - - `"auto"` + - `type: "apply_patch"` - - `"low"` + The type of the tool. Always `apply_patch`. - - `"high"` + - `"apply_patch"` - - `type: "image_file"` + - `allowed_callers: optional array of "direct" or "programmatic"` - Always `image_file`. + The tool invocation context(s). - - `"image_file"` + - `"direct"` - - `ImageURLContentBlock object { image_url, type }` + - `"programmatic"` - References an image URL in the content of a message. + - `top_p: number` - - `image_url: ImageURL` + 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. - - `url: string` + We generally recommend altering this or `temperature` but not both. - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `background: optional boolean` - - `detail: optional "auto" or "low" or "high"` + Whether to run the model response in the background. + [Learn more](/docs/guides/background). - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + - `completed_at: optional number` - - `"auto"` + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - - `"low"` + - `conversation: optional object { id }` - - `"high"` + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - - `type: "image_url"` + - `id: string` - The type of the content part. + The unique ID of the conversation that this response was associated with. - - `"image_url"` + - `max_output_tokens: optional number` - - `TextContentBlock object { text, type }` + 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 text content that is part of a message. + - `max_tool_calls: optional number` - - `text: Text` + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. - - `annotations: array of Annotation` + - `moderation: optional object { input, output }` - - `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` + Moderation results for the response input and output, if moderated completions were requested. - 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. + - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` - - `end_index: number` + Moderation for the response input. - - `file_citation: object { file_id }` + - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` - - `file_id: string` + A moderation result produced for the response input or output. - The ID of the specific File the citation is from. + - `categories: map[boolean]` - - `start_index: number` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `text: string` + - `category_applied_input_types: map[array of "text" or "image"]` - The text in the message content that needs to be replaced. + Which modalities of input are reflected by the score for each category. - - `type: "file_citation"` + - `"text"` - Always `file_citation`. + - `"image"` - - `"file_citation"` + - `category_scores: map[number]` - - `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` + A dictionary of moderation categories to scores. - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + - `flagged: boolean` - - `end_index: number` + A boolean indicating whether the content was flagged by any category. - - `file_path: object { file_id }` + - `model: string` - - `file_id: string` + The moderation model that produced this result. - The ID of the file that was generated. + - `type: "moderation_result"` - - `start_index: number` + The object type, which was always `moderation_result` for successful moderation results. - - `text: string` + - `"moderation_result"` - The text in the message content that needs to be replaced. + - `Error object { code, message, type }` - - `type: "file_path"` + An error produced while attempting moderation for the response input or output. - Always `file_path`. + - `code: string` - - `"file_path"` + The error code. - - `value: string` + - `message: string` - The data that makes up the text. + The error message. - - `type: "text"` + - `type: "error"` - Always `text`. + The object type, which was always `error` for moderation failures. - - `"text"` + - `"error"` - - `RefusalContentBlock object { refusal, type }` + - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` - The refusal content generated by the assistant. + Moderation for the response output. - - `refusal: string` + - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` - - `type: "refusal"` + A moderation result produced for the response input or output. - Always `refusal`. + - `categories: map[boolean]` - - `"refusal"` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `created_at: number` + - `category_applied_input_types: map[array of "text" or "image"]` - The Unix timestamp (in seconds) for when the message was created. + Which modalities of input are reflected by the score for each category. - - `incomplete_at: number` + - `"text"` - The Unix timestamp (in seconds) for when the message was marked as incomplete. + - `"image"` - - `incomplete_details: object { reason }` + - `category_scores: map[number]` - On an incomplete message, details about why the message is incomplete. + A dictionary of moderation categories to scores. - - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` + - `flagged: boolean` - The reason the message is incomplete. + A boolean indicating whether the content was flagged by any category. - - `"content_filter"` + - `model: string` - - `"max_tokens"` + The moderation model that produced this result. - - `"run_cancelled"` + - `type: "moderation_result"` - - `"run_expired"` + The object type, which was always `moderation_result` for successful moderation results. - - `"run_failed"` + - `"moderation_result"` - - `metadata: Metadata` + - `Error object { code, message, 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. + An error produced while attempting moderation for the response input or output. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `code: string` - - `object: "thread.message"` + The error code. - The object type, which is always `thread.message`. + - `message: string` - - `"thread.message"` + The error message. - - `role: "user" or "assistant"` + - `type: "error"` - The entity that produced the message. One of `user` or `assistant`. + The object type, which was always `error` for moderation failures. - - `"user"` + - `"error"` - - `"assistant"` + - `output_text: optional string` - - `run_id: 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 ID of the [run](https://platform.openai.com/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. + - `previous_response_id: optional string` - - `status: "in_progress" or "incomplete" or "completed"` + The unique ID of the previous response to the model. Use this to + create multi-turn conversations. Learn more about + [conversation state](/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + - `prompt: optional BetaResponsePrompt` - - `"in_progress"` + Reference to a prompt template and its variables. + [Learn more](/docs/guides/text?api-mode=responses#reusable-prompts). - - `"incomplete"` + - `id: string` - - `"completed"` + The unique identifier of the prompt template to use. - - `thread_id: string` + - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` - The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + 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. -### Example + - `string` -```http -curl https://api.openai.com/v1/threads/$THREAD_ID/messages/$MESSAGE_ID \ - -H 'OpenAI-Beta: assistants=v2' \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` -#### Response + A text input to the model. -```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" -} -``` + - `BetaResponseInputImage object { detail, type, 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/threads/thread_abc123/messages/msg_abc123 \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "OpenAI-Beta: assistants=v2" -``` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` -#### Response + A file input to the model. -```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": {} -} -``` + - `version: optional string` -## Delete message + Optional version of the prompt template. -**delete** `/threads/{thread_id}/messages/{message_id}` + - `prompt_cache_key: optional string` -Delete message + 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). -### Path Parameters + - `prompt_cache_options: optional object { mode, ttl }` -- `thread_id: string` + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. -- `message_id: string` + - `mode: "implicit" or "explicit"` -### Returns + Whether implicit prompt-cache breakpoints were enabled. -- `MessageDeleted object { id, deleted, object }` + - `"implicit"` - - `id: string` + - `"explicit"` - - `deleted: boolean` + - `ttl: "30m"` - - `object: "thread.message.deleted"` + The minimum lifetime applied to each cache breakpoint. - - `"thread.message.deleted"` + - `"30m"` -### Example + - `prompt_cache_retention: optional "in_memory" or "24h"` -```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" -``` + Deprecated. Use `prompt_cache_options.ttl` instead. -#### Response + 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. -```json -{ - "id": "id", - "deleted": true, - "object": "thread.message.deleted" -} -``` + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: -### Example + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. -```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" -``` + - `"in_memory"` -#### Response + - `"24h"` -```json -{ - "id": "msg_abc123", - "object": "thread.message.deleted", - "deleted": true -} -``` + - `reasoning: optional object { context, effort, generate_summary, 2 more }` -## Domain Types + **gpt-5 and o-series models only** -### Annotation + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). -- `Annotation = FileCitationAnnotation or FilePathAnnotation` + - `context: optional "auto" or "current_turn" or "all_turns"` - 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. + Controls which reasoning items are rendered back to the model on later turns. + When returned on a response, this is the effective reasoning context mode + used for the response. - - `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` + - `"auto"` - 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. + - `"current_turn"` - - `end_index: number` + - `"all_turns"` - - `file_citation: object { file_id }` + - `effort: optional "none" or "minimal" or "low" or 4 more` - - `file_id: 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 ID of the specific File the citation is from. + - `"none"` - - `start_index: number` + - `"minimal"` - - `text: string` + - `"low"` - The text in the message content that needs to be replaced. + - `"medium"` - - `type: "file_citation"` + - `"high"` - Always `file_citation`. + - `"xhigh"` - - `"file_citation"` + - `"max"` - - `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` + - `generate_summary: optional "auto" or "concise" or "detailed"` - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + **Deprecated:** use `summary` instead. - - `end_index: 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`. - - `file_path: object { file_id }` + - `"auto"` - - `file_id: string` + - `"concise"` - The ID of the file that was generated. + - `"detailed"` - - `start_index: number` + - `mode: optional string or "standard" or "pro"` - - `text: string` + Controls the reasoning execution mode for the request. - The text in the message content that needs to be replaced. + When returned on a response, this is the effective execution mode. - - `type: "file_path"` + - `string` - Always `file_path`. + - `"standard" or "pro"` - - `"file_path"` + Controls the reasoning execution mode for the request. -### Annotation Delta + When returned on a response, this is the effective execution mode. -- `AnnotationDelta = FileCitationDeltaAnnotation or FilePathDeltaAnnotation` + - `"standard"` - 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. + - `"pro"` - - `FileCitationDeltaAnnotation object { index, type, end_index, 3 more }` + - `summary: optional "auto" or "concise" or "detailed"` - 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. + 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`. - - `index: number` + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - The index of the annotation in the text content part. + - `"auto"` - - `type: "file_citation"` + - `"concise"` - Always `file_citation`. + - `"detailed"` - - `"file_citation"` + - `safety_identifier: optional string` - - `end_index: optional number` + 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). - - `file_citation: optional object { file_id, quote }` + - `service_tier: optional "auto" or "default" or "flex" or 2 more` - - `file_id: optional string` + Specifies the processing type used for serving the request. - The ID of the specific File the citation is from. + - 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'. - - `quote: 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 specific quote in the file. + - `"auto"` - - `start_index: optional number` + - `"default"` - - `text: optional string` + - `"flex"` - The text in the message content that needs to be replaced. + - `"scale"` - - `FilePathDeltaAnnotation object { index, type, end_index, 3 more }` + - `"priority"` - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + - `status: optional BetaResponseStatus` - - `index: number` + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - The index of the annotation in the text content part. + - `"completed"` - - `type: "file_path"` + - `"failed"` - Always `file_path`. + - `"in_progress"` - - `"file_path"` + - `"cancelled"` - - `end_index: optional number` + - `"queued"` - - `file_path: optional object { file_id }` + - `"incomplete"` - - `file_id: optional string` + - `text: optional BetaResponseTextConfig` - The ID of the file that was generated. + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - - `start_index: optional number` + - [Text inputs and outputs](/docs/guides/text) + - [Structured Outputs](/docs/guides/structured-outputs) - - `text: optional string` + - `format: optional BetaResponseFormatTextConfig` - The text in the message content that needs to be replaced. + An object specifying the format that the model must output. -### File Citation Annotation + 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). -- `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` + The default format is `{ "type": "text" }` with no additional options. - 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. + **Not recommended for gpt-4o and newer models:** - - `end_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. - - `file_citation: object { file_id }` + - `Text object { type }` - - `file_id: string` + Default response format. Used to generate text responses. - The ID of the specific File the citation is from. + - `type: "text"` - - `start_index: number` + The type of response format being defined. Always `text`. - - `text: string` + - `"text"` - The text in the message content that needs to be replaced. + - `BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` - - `type: "file_citation"` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - Always `file_citation`. + - `name: string` - - `"file_citation"` + 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 Citation Delta Annotation + - `schema: map[unknown]` -- `FileCitationDeltaAnnotation object { index, type, end_index, 3 more }` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - 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: "json_schema"` - - `index: number` + The type of response format being defined. Always `json_schema`. - The index of the annotation in the text content part. + - `"json_schema"` - - `type: "file_citation"` + - `description: optional string` - Always `file_citation`. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `"file_citation"` + - `strict: optional boolean` - - `end_index: optional 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). - - `file_citation: optional object { file_id, quote }` + - `JSONObject object { type }` - - `file_id: 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. - The ID of the specific File the citation is from. + - `type: "json_object"` - - `quote: optional string` + The type of response format being defined. Always `json_object`. - The specific quote in the file. + - `"json_object"` - - `start_index: optional number` + - `verbosity: optional "low" or "medium" or "high"` - - `text: 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 text in the message content that needs to be replaced. + - `"low"` -### File Path Annotation + - `"medium"` -- `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` + - `"high"` - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + - `top_logprobs: optional number` - - `end_index: 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. - - `file_path: object { file_id }` + - `truncation: optional "auto" or "disabled"` - - `file_id: string` + The truncation strategy to use for the model response. - The ID of the file that was generated. + - `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. - - `start_index: number` + - `"auto"` - - `text: string` + - `"disabled"` - The text in the message content that needs to be replaced. + - `usage: optional BetaResponseUsage` - - `type: "file_path"` + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - Always `file_path`. + - `input_tokens: number` - - `"file_path"` + The number of input tokens. -### File Path Delta Annotation + - `input_tokens_details: object { cache_write_tokens, cached_tokens }` -- `FilePathDeltaAnnotation object { index, type, end_index, 3 more }` + A detailed breakdown of the input tokens. - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + - `cache_write_tokens: number` - - `index: number` + The number of input tokens that were written to the cache. - The index of the annotation in the text content part. + - `cached_tokens: number` - - `type: "file_path"` + The number of tokens that were retrieved from the cache. + [More on prompt caching](/docs/guides/prompt-caching). - Always `file_path`. + - `output_tokens: number` - - `"file_path"` + The number of output tokens. - - `end_index: optional number` + - `output_tokens_details: object { reasoning_tokens }` - - `file_path: optional object { file_id }` + A detailed breakdown of the output tokens. - - `file_id: optional string` + - `reasoning_tokens: number` - The ID of the file that was generated. + The number of reasoning tokens. - - `start_index: optional number` + - `total_tokens: number` - - `text: optional string` + The total number of tokens used. - The text in the message content that needs to be replaced. + - `user: optional string` -### Image File + 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). -- `ImageFile object { file_id, detail }` +### Example + +```http +curl https://api.openai.com/v1/responses \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "gpt-5.1", + "prompt_cache_key": "prompt-cache-key-1234", + "safety_identifier": "safety-identifier-1234", + "temperature": 1, + "top_p": 1, + "user": "user-1234" + }' +``` + +#### Response + +```json +{ + "id": "id", + "created_at": 0, + "error": { + "code": "server_error", + "message": "message" + }, + "incomplete_details": { + "reason": "max_output_tokens" + }, + "instructions": "string", + "metadata": { + "foo": "string" + }, + "model": "gpt-5.1", + "object": "response", + "output": [ + { + "id": "id", + "content": [ + { + "annotations": [ + { + "file_id": "file_id", + "filename": "filename", + "index": 0, + "type": "file_citation" + } + ], + "logprobs": [ + { + "token": "token", + "bytes": [ + 0 + ], + "logprob": 0, + "top_logprobs": [ + { + "token": "token", + "bytes": [ + 0 + ], + "logprob": 0 + } + ] + } + ], + "text": "text", + "type": "output_text" + } + ], + "role": "assistant", + "status": "in_progress", + "type": "message", + "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" +} +``` + +### Text input + +```http +curl https://api.openai.com/v1/responses \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "gpt-5.4", + "input": "Tell me a three sentence bedtime story about a unicorn." + }' +``` + +#### Response + +```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 + }, + "output_tokens": 87, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 123 + }, + "user": null, + "metadata": {} +} +``` + +### Image input + +```http +curl https://api.openai.com/v1/responses \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "gpt-5.4", + "input": [ + { + "role": "user", + "content": [ + {"type": "input_text", "text": "what is in this image?"}, + { + "type": "input_image", + "image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg" + } + ] + } + ] + }' +``` + +#### Response + +```json +{ + "id": "resp_67ccd3a9da748190baa7f1570fe91ac604becb25c45c1d41", + "object": "response", + "created_at": 1741476777, + "status": "completed", + "completed_at": 1741476778, + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "gpt-5.4", + "output": [ + { + "type": "message", + "id": "msg_67ccd3acc8d48190a77525dc6de64b4104becb25c45c1d41", + "status": "completed", + "role": "assistant", + "content": [ + { + "type": "output_text", + "text": "The image depicts a scenic landscape with a wooden boardwalk or pathway leading through lush, green grass under a blue sky with some clouds. The setting suggests a peaceful natural area, possibly a park or nature reserve. There are trees and shrubs in the background.", + "annotations": [] + } + ] + } + ], + "parallel_tool_calls": true, + "previous_response_id": null, + "reasoning": { + "effort": null, + "summary": null + }, + "store": true, + "temperature": 1.0, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [], + "top_p": 1.0, + "truncation": "disabled", + "usage": { + "input_tokens": 328, + "input_tokens_details": { + "cached_tokens": 0 + }, + "output_tokens": 52, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 380 + }, + "user": null, + "metadata": {} +} +``` + +### File input + +```http +curl https://api.openai.com/v1/responses \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "gpt-5.4", + "input": [ + { + "role": "user", + "content": [ + {"type": "input_text", "text": "what is in this file?"}, + { + "type": "input_file", + "file_url": "https://www.berkshirehathaway.com/letters/2024ltr.pdf", + "detail": "auto" + } + ] + } + ] + }' +``` + +#### Response + +```json +{ + "id": "resp_686eef60237881a2bd1180bb8b13de430e34c516d176ff86", + "object": "response", + "created_at": 1752100704, + "status": "completed", + "completed_at": 1752100705, + "background": false, + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "max_tool_calls": null, + "model": "gpt-5.4", + "output": [ + { + "id": "msg_686eef60d3e081a29283bdcbc4322fd90e34c516d176ff86", + "type": "message", + "status": "completed", + "content": [ + { + "type": "output_text", + "annotations": [], + "logprobs": [], + "text": "The file seems to contain excerpts from a letter to the shareholders of Berkshire Hathaway Inc., likely written by Warren Buffett. It covers several topics:\n\n1. **Communication Philosophy**: Buffett emphasizes the importance of transparency and candidness in reporting mistakes and successes to shareholders.\n\n2. **Mistakes and Learnings**: The letter acknowledges past mistakes in business assessments and management hires, highlighting the importance of correcting errors promptly.\n\n3. **CEO Succession**: Mention of Greg Abel stepping in as the new CEO and continuing the tradition of honest communication.\n\n4. **Pete Liegl Story**: A detailed account of acquiring Forest River and the relationship with its founder, highlighting trust and effective business decisions.\n\n5. **2024 Performance**: Overview of business performance, particularly in insurance and investment activities, with a focus on GEICO's improvement.\n\n6. **Tax Contributions**: Discussion of significant tax payments to the U.S. Treasury, credited to shareholders' reinvestments.\n\n7. **Investment Strategy**: A breakdown of Berkshire\u2019s investments in both controlled subsidiaries and marketable equities, along with a focus on long-term holding strategies.\n\n8. **American Capitalism**: Reflections on America\u2019s economic development and Berkshire\u2019s role within it.\n\n9. **Property-Casualty Insurance**: Insights into the P/C insurance business model and its challenges and benefits.\n\n10. **Japanese Investments**: Information about Berkshire\u2019s investments in Japanese companies and future plans.\n\n11. **Annual Meeting**: Details about the upcoming annual gathering in Omaha, including schedule changes and new book releases.\n\n12. **Personal Anecdotes**: Light-hearted stories about family and interactions, conveying Buffett's personable approach.\n\n13. **Financial Performance Data**: Tables comparing Berkshire\u2019s annual performance to the S&P 500, showing impressive long-term gains.\n\nOverall, the letter reinforces Berkshire Hathaway's commitment to transparency, investment in both its businesses and the wider economy, and emphasizes strong leadership and prudent financial management." + } + ], + "role": "assistant" + } + ], + "parallel_tool_calls": true, + "previous_response_id": null, + "reasoning": { + "effort": null, + "summary": null + }, + "service_tier": "default", + "store": true, + "temperature": 1.0, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [], + "top_logprobs": 0, + "top_p": 1.0, + "truncation": "disabled", + "usage": { + "input_tokens": 8438, + "input_tokens_details": { + "cached_tokens": 0 + }, + "output_tokens": 398, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 8836 + }, + "user": null, + "metadata": {} +} +``` + +### Web search + +```http +curl https://api.openai.com/v1/responses \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "gpt-5.4", + "tools": [{ "type": "web_search_preview" }], + "input": "What was a positive news story from today?" + }' +``` + +#### Response + +```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 + }, + "output_tokens": 356, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 684 + }, + "user": null, + "metadata": {} +} +``` + +### File search + +```http +curl https://api.openai.com/v1/responses \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "gpt-5.4", + "tools": [{ + "type": "file_search", + "vector_store_ids": ["vs_1234567890"], + "max_num_results": 20 + }], + "input": "What are the attributes of an ancient brown dragon?" + }' +``` + +#### Response + +```json +{ + "id": "resp_67ccf4c55fc48190b71bd0463ad3306d09504fb6872380d7", + "object": "response", + "created_at": 1741485253, + "status": "completed", + "completed_at": 1741485254, + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "gpt-5.4", + "output": [ + { + "type": "file_search_call", + "id": "fs_67ccf4c63cd08190887ef6464ba5681609504fb6872380d7", + "status": "completed", + "queries": [ + "attributes of an ancient brown dragon" + ], + "results": null + }, + { + "type": "message", + "id": "msg_67ccf4c93e5c81909d595b369351a9d309504fb6872380d7", + "status": "completed", + "role": "assistant", + "content": [ + { + "type": "output_text", + "text": "The attributes of an ancient brown dragon include...", + "annotations": [ + { + "type": "file_citation", + "index": 320, + "file_id": "file-4wDz5b167pAf72nx1h9eiN", + "filename": "dragons.pdf" + }, + { + "type": "file_citation", + "index": 576, + "file_id": "file-4wDz5b167pAf72nx1h9eiN", + "filename": "dragons.pdf" + }, + { + "type": "file_citation", + "index": 815, + "file_id": "file-4wDz5b167pAf72nx1h9eiN", + "filename": "dragons.pdf" + }, + { + "type": "file_citation", + "index": 815, + "file_id": "file-4wDz5b167pAf72nx1h9eiN", + "filename": "dragons.pdf" + }, + { + "type": "file_citation", + "index": 1030, + "file_id": "file-4wDz5b167pAf72nx1h9eiN", + "filename": "dragons.pdf" + }, + { + "type": "file_citation", + "index": 1030, + "file_id": "file-4wDz5b167pAf72nx1h9eiN", + "filename": "dragons.pdf" + }, + { + "type": "file_citation", + "index": 1156, + "file_id": "file-4wDz5b167pAf72nx1h9eiN", + "filename": "dragons.pdf" + }, + { + "type": "file_citation", + "index": 1225, + "file_id": "file-4wDz5b167pAf72nx1h9eiN", + "filename": "dragons.pdf" + } + ] + } + ] + } + ], + "parallel_tool_calls": true, + "previous_response_id": null, + "reasoning": { + "effort": null, + "summary": null + }, + "store": true, + "temperature": 1.0, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [ + { + "type": "file_search", + "filters": null, + "max_num_results": 20, + "ranking_options": { + "ranker": "auto", + "score_threshold": 0.0 + }, + "vector_store_ids": [ + "vs_1234567890" + ] + } + ], + "top_p": 1.0, + "truncation": "disabled", + "usage": { + "input_tokens": 18307, + "input_tokens_details": { + "cached_tokens": 0 + }, + "output_tokens": 348, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 18655 + }, + "user": null, + "metadata": {} +} +``` + +### Streaming + +```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 + }' +``` + +#### Response + +```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":{}}} + +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":{}}} + +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":[]}} + +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":[]}} + +event: response.output_text.delta +data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"Hi"} + +... + +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?"} + +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":[]}} + +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":[]}]}} + +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":{}}} +``` + +### Functions + +```http +curl https://api.openai.com/v1/responses \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "gpt-5.4", + "input": "What is the weather like in Boston today?", + "tools": [ + { + "type": "function", + "name": "get_current_weather", + "description": "Get the current weather in a given location", + "parameters": { + "type": "object", + "properties": { + "location": { + "type": "string", + "description": "The city and state, e.g. San Francisco, CA" + }, + "unit": { + "type": "string", + "enum": ["celsius", "fahrenheit"] + } + }, + "required": ["location", "unit"] + } + } + ], + "tool_choice": "auto" + }' +``` + +#### Response + +```json +{ + "id": "resp_67ca09c5efe0819096d0511c92b8c890096610f474011cc0", + "object": "response", + "created_at": 1741294021, + "status": "completed", + "completed_at": 1741294022, + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "gpt-5.4", + "output": [ + { + "type": "function_call", + "id": "fc_67ca09c6bedc8190a7abfec07b1a1332096610f474011cc0", + "call_id": "call_unLAR8MvFNptuiZK6K6HCy5k", + "name": "get_current_weather", + "arguments": "{\"location\":\"Boston, MA\",\"unit\":\"celsius\"}", + "status": "completed" + } + ], + "parallel_tool_calls": true, + "previous_response_id": null, + "reasoning": { + "effort": null, + "summary": null + }, + "store": true, + "temperature": 1.0, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [ + { + "type": "function", + "description": "Get the current weather in a given location", + "name": "get_current_weather", + "parameters": { + "type": "object", + "properties": { + "location": { + "type": "string", + "description": "The city and state, e.g. San Francisco, CA" + }, + "unit": { + "type": "string", + "enum": [ + "celsius", + "fahrenheit" + ] + } + }, + "required": [ + "location", + "unit" + ] + }, + "strict": true + } + ], + "top_p": 1.0, + "truncation": "disabled", + "usage": { + "input_tokens": 291, + "output_tokens": 23, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 314 + }, + "user": null, + "metadata": {} +} +``` + +### Reasoning + +```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" + } + }' +``` + +#### Response + +```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 + }, + "output_tokens": 1035, + "output_tokens_details": { + "reasoning_tokens": 832 + }, + "total_tokens": 1116 + }, + "user": null, + "metadata": {} +} +``` + +## Get a model response + +**get** `/responses/{response_id}?beta=true` + +Retrieves a model response with the given ID. + +### Path Parameters + +- `response_id: string` + +### Query Parameters + +- `include: optional array of BetaResponseIncludable` + + Additional fields to include in the response. See the `include` + parameter for Response creation above for more information. + + - `"file_search_call.results"` + + - `"web_search_call.results"` + + - `"web_search_call.action.sources"` + + - `"message.input_image.image_url"` + + - `"computer_call_output.output.image_url"` + + - `"code_interpreter_call.outputs"` + + - `"reasoning.encrypted_content"` + + - `"message.output_text.logprobs"` + +- `include_obfuscation: optional boolean` + + 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. + +- `starting_after: optional number` + + The sequence number of the event after which to start streaming. + +- `stream: optional false` + + 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. + + - `false` + +### Header Parameters + +- `"openai-beta": optional array of "responses_multi_agent=v1"` + + - `"responses_multi_agent=v1"` + +### Returns + +- `BetaResponse object { id, created_at, error, 32 more }` + + - `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 16 more` + + The error code for the response. + + - `"server_error"` + + - `"rate_limit_exceeded"` + + - `"invalid_prompt"` + + - `"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 }` + + 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"` + + - `"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 item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: optional "message"` + + The type of the message input. Always set to `message`. + + - `"message"` + + - `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"` + + - `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. + + - `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 { 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 array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` + + Citations associated with the text content. + + - `array of 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"` + + - `array of 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. + + - `array of 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` + + 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 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. + + - `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 output. + + - `"in_progress"` + + - `"completed"` + + - `"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` + + A list of additional tools made available at this item. + + - `Function object { name, parameters, strict, 5 more }` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `name: string` + + The name of the function to call. + + - `parameters: map[unknown]` + + A JSON schema object describing the parameters of the function. + + - `strict: boolean` + + Whether strict parameter validation is enforced for this function tool. + + - `type: "function"` + + The type of the function tool. Always `function`. + + - `"function"` + + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `defer_loading: optional boolean` + + Whether this function is deferred and loaded via tool search. + + - `description: optional string` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `output_schema: optional map[unknown]` + + A JSON schema object describing the JSON value encoded in string outputs for this function. + + - `FileSearch object { type, vector_store_ids, filters, 2 more }` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: "file_search"` + + The type of the file search tool. Always `file_search`. + + - `"file_search"` + + - `vector_store_ids: array of string` + + The IDs of the vector stores to search. + + - `filters: optional 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). - - `file_id: string` + - `type: "computer"` - The [File](https://platform.openai.com/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 type of the computer tool. Always `computer`. - - `detail: optional "auto" or "low" or "high"` + - `"computer"` - 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`. + - `ComputerUsePreview object { display_height, display_width, environment, type }` - - `"auto"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"low"` + - `display_height: number` - - `"high"` + The height of the computer display. -### Image File Content Block + - `display_width: number` -- `ImageFileContentBlock object { image_file, type }` + The width of the computer display. - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + - `environment: "windows" or "mac" or "linux" or 2 more` - - `image_file: ImageFile` + The type of computer environment to control. - - `file_id: string` + - `"windows"` - The [File](https://platform.openai.com/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. + - `"mac"` - - `detail: optional "auto" or "low" or "high"` + - `"linux"` - 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`. + - `"ubuntu"` - - `"auto"` + - `"browser"` - - `"low"` + - `type: "computer_use_preview"` - - `"high"` + The type of the computer use tool. Always `computer_use_preview`. - - `type: "image_file"` + - `"computer_use_preview"` - Always `image_file`. + - `WebSearch object { type, filters, search_context_size, user_location }` - - `"image_file"` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). -### Image File Delta + - `type: "web_search" or "web_search_2025_08_26"` -- `ImageFileDelta object { detail, file_id }` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `detail: optional "auto" or "low" or "high"` + - `"web_search"` - 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`. + - `"web_search_2025_08_26"` - - `"auto"` + - `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"` - - `file_id: optional string` + - `user_location: optional object { city, country, region, 2 more }` - The [File](https://platform.openai.com/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 approximate location of the user. -### Image File Delta Block + - `city: optional string` -- `ImageFileDeltaBlock object { index, type, image_file }` + Free text input for the city of the user, e.g. `San Francisco`. - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + - `country: optional string` - - `index: number` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The index of the content part in the message. + - `region: optional string` - - `type: "image_file"` + Free text input for the region of the user, e.g. `California`. - Always `image_file`. + - `timezone: optional string` - - `"image_file"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `image_file: optional ImageFileDelta` + - `type: optional "approximate"` - - `detail: optional "auto" or "low" or "high"` + The type of location approximation. Always `approximate`. - 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`. + - `"approximate"` - - `"auto"` + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `"low"` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - - `"high"` + - `server_label: string` - - `file_id: optional string` + A label for this MCP server, used to identify it in tool calls. - The [File](https://platform.openai.com/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. + - `type: "mcp"` -### Image URL + The type of the MCP tool. Always `mcp`. -- `ImageURL object { url, detail }` + - `"mcp"` - - `url: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + The tool invocation context(s). - - `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`. Default value is `auto` + - `"programmatic"` - - `"auto"` + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `"low"` + List of allowed tool names or a filter object. - - `"high"` + - `McpAllowedTools = array of string` -### Image URL Content Block + A string array of allowed tool names -- `ImageURLContentBlock object { image_url, type }` + - `McpToolFilter object { read_only, tool_names }` - References an image URL in the content of a message. + A filter object to specify which tools are allowed. - - `image_url: ImageURL` + - `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 external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `tool_names: optional array of string` - - `detail: optional "auto" or "low" or "high"` + List of allowed tool names. - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + - `authorization: optional string` - - `"auto"` + 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. - - `"low"` + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `"high"` + 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: "image_url"` + Currently supported `connector_id` values are: - The type of the content part. + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - - `"image_url"` + - `"connector_dropbox"` -### Image URL Delta + - `"connector_gmail"` -- `ImageURLDelta object { detail, url }` + - `"connector_googlecalendar"` - - `detail: optional "auto" or "low" or "high"` + - `"connector_googledrive"` - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. + - `"connector_microsoftteams"` - - `"auto"` + - `"connector_outlookcalendar"` - - `"low"` + - `"connector_outlookemail"` - - `"high"` + - `"connector_sharepoint"` - - `url: optional string` + - `defer_loading: optional boolean` - The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + Whether this MCP tool is deferred and discovered via tool search. -### Image URL Delta Block + - `headers: optional map[string]` -- `ImageURLDeltaBlock object { index, type, image_url }` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - References an image URL in the content of a message. + - `require_approval: optional object { always, never } or "always" or "never"` - - `index: number` + Specify which of the MCP server's tools require approval. - The index of the content part in the message. + - `McpToolApprovalFilter object { always, never }` - - `type: "image_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. - Always `image_url`. + - `always: optional object { read_only, tool_names }` - - `"image_url"` + A filter object to specify which tools are allowed. - - `image_url: optional ImageURLDelta` + - `read_only: optional boolean` - - `detail: optional "auto" or "low" or "high"` + 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 detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. + - `tool_names: optional array of string` - - `"auto"` + List of allowed tool names. - - `"low"` + - `never: optional object { read_only, tool_names }` - - `"high"` + A filter object to specify which tools are allowed. - - `url: optional string` + - `read_only: optional boolean` - The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + 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` -- `Message object { id, assistant_id, attachments, 11 more }` + List of allowed tool names. - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + - `McpToolApprovalSetting = "always" or "never"` - - `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 identifier, which can be referenced in API endpoints. + - `"always"` - - `assistant_id: string` + - `"never"` - If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. + - `server_description: optional string` - - `attachments: array of object { file_id, tools }` + Optional description of the MCP server, used to provide more context. - A list of files attached to the message, and the tools they were added to. + - `server_url: optional string` - - `file_id: optional string` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - The ID of the file to attach to the message. + - `tunnel_id: optional string` - - `tools: optional array of CodeInterpreterTool or 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. - The tools to add this file to. + - `CodeInterpreter object { container, type, allowed_callers }` - - `CodeInterpreterTool object { type }` + A tool that runs Python code to help generate a response to a prompt. - - `type: "code_interpreter"` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - The type of tool being defined: `code_interpreter` + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - - `"code_interpreter"` + - `string` - - `AssistantToolsFileSearchTypeOnly object { type }` + The container ID. - - `type: "file_search"` + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - The type of tool being defined: `file_search` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `"file_search"` + - `type: "auto"` - - `completed_at: number` + Always `auto`. - The Unix timestamp (in seconds) for when the message was completed. + - `"auto"` - - `content: array of MessageContent` + - `file_ids: optional array of string` - The content of the message in array of text and/or images. + An optional list of uploaded files to make available to your code. - - `ImageFileContentBlock object { image_file, type }` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + The memory limit for the code interpreter container. - - `image_file: ImageFile` + - `"1g"` - - `file_id: string` + - `"4g"` - The [File](https://platform.openai.com/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. + - `"16g"` - - `detail: optional "auto" or "low" or "high"` + - `"64g"` - 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`. + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `"auto"` + Network access policy for the container. - - `"low"` + - `BetaContainerNetworkPolicyDisabled object { type }` - - `"high"` + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `type: "image_file"` + - `type: "code_interpreter"` - Always `image_file`. + The type of the code interpreter tool. Always `code_interpreter`. - - `"image_file"` + - `"code_interpreter"` - - `ImageURLContentBlock object { image_url, type }` + - `allowed_callers: optional array of "direct" or "programmatic"` - References an image URL in the content of a message. + The tool invocation context(s). - - `image_url: ImageURL` + - `"direct"` - - `url: string` + - `"programmatic"` - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `ProgrammaticToolCalling object { type }` - - `detail: optional "auto" or "low" or "high"` + - `type: "programmatic_tool_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` + 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"` - - `"low"` + - `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"` - - `type: "image_url"` + - `"low"` - The type of the content part. + - `input_image_mask: optional object { file_id, image_url }` - - `"image_url"` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `TextContentBlock object { text, type }` + - `file_id: optional string` - The text content that is part of a message. + File ID for the mask image. - - `text: Text` + - `image_url: optional string` - - `annotations: array of Annotation` + Base64-encoded mask image. - - `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - 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 image generation model to use. Default: `gpt-image-1`. - - `end_index: number` + - `string` - - `file_citation: object { file_id }` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `file_id: string` + The image generation model to use. Default: `gpt-image-1`. - The ID of the specific File the citation is from. + - `"gpt-image-1"` - - `start_index: number` + - `"gpt-image-1-mini"` - - `text: string` + - `"gpt-image-1.5"` - The text in the message content that needs to be replaced. + - `moderation: optional "auto" or "low"` - - `type: "file_citation"` + Moderation level for the generated image. Default: `auto`. - Always `file_citation`. + - `"auto"` - - `"file_citation"` + - `"low"` - - `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` + - `output_compression: optional number` - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + Compression level for the output image. Default: 100. - - `end_index: number` + - `output_format: optional "png" or "webp" or "jpeg"` - - `file_path: object { file_id }` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `file_id: string` + - `"png"` - The ID of the file that was generated. + - `"webp"` - - `start_index: number` + - `"jpeg"` - - `text: string` + - `partial_images: optional number` - The text in the message content that needs to be replaced. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `type: "file_path"` + - `quality: optional "low" or "medium" or "high" or "auto"` - Always `file_path`. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `"file_path"` + - `"low"` - - `value: string` + - `"medium"` - The data that makes up the text. + - `"high"` - - `type: "text"` + - `"auto"` - Always `text`. + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `"text"` + 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`. - - `RefusalContentBlock object { refusal, type }` + - `string` - The refusal content generated by the assistant. + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `refusal: 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`. - - `type: "refusal"` + - `"1024x1024"` - Always `refusal`. + - `"1024x1536"` - - `"refusal"` + - `"1536x1024"` - - `created_at: number` + - `"auto"` - The Unix timestamp (in seconds) for when the message was created. + - `LocalShell object { type }` - - `incomplete_at: number` + A tool that allows the model to execute shell commands in a local environment. - The Unix timestamp (in seconds) for when the message was marked as incomplete. + - `type: "local_shell"` - - `incomplete_details: object { reason }` + The type of the local shell tool. Always `local_shell`. - On an incomplete message, details about why the message is incomplete. + - `"local_shell"` - - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` + - `Shell object { type, allowed_callers, environment }` - The reason the message is incomplete. + A tool that allows the model to execute shell commands. - - `"content_filter"` + - `type: "shell"` - - `"max_tokens"` + The type of the shell tool. Always `shell`. - - `"run_cancelled"` + - `"shell"` - - `"run_expired"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"run_failed"` + The tool invocation context(s). - - `metadata: Metadata` + - `"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. + - `"programmatic"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - `object: "thread.message"` + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - The object type, which is always `thread.message`. + - `BetaLocalEnvironment object { type, skills }` - - `"thread.message"` + - `BetaContainerReference object { container_id, type }` - - `role: "user" or "assistant"` + - `Custom object { name, type, allowed_callers, 3 more }` - The entity that produced the message. One of `user` or `assistant`. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `"user"` + - `name: string` - - `"assistant"` + The name of the custom tool, used to identify it in tool calls. - - `run_id: string` + - `type: "custom"` - The ID of the [run](https://platform.openai.com/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 type of the custom tool. Always `custom`. - - `status: "in_progress" or "incomplete" or "completed"` + - `"custom"` - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"in_progress"` + The tool invocation context(s). - - `"incomplete"` + - `"direct"` - - `"completed"` + - `"programmatic"` - - `thread_id: string` + - `defer_loading: optional boolean` - The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + Whether this tool should be deferred and discovered via tool search. -### Message Content + - `description: optional string` -- `MessageContent = ImageFileContentBlock or ImageURLContentBlock or TextContentBlock or RefusalContentBlock` + Optional description of the custom tool, used to provide more context. - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + - `format: optional object { type } or object { definition, syntax, type }` - - `ImageFileContentBlock object { image_file, type }` + The input format for the custom tool. Default is unconstrained text. - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + - `Text object { type }` - - `image_file: ImageFile` + Unconstrained free-form text. - - `file_id: string` + - `type: "text"` - The [File](https://platform.openai.com/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. + Unconstrained text format. Always `text`. - - `detail: optional "auto" or "low" or "high"` + - `"text"` - 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`. + - `Grammar object { definition, syntax, type }` - - `"auto"` + A grammar defined by the user. - - `"low"` + - `definition: string` - - `"high"` + The grammar definition. - - `type: "image_file"` + - `syntax: "lark" or "regex"` - Always `image_file`. + The syntax of the grammar definition. One of `lark` or `regex`. - - `"image_file"` + - `"lark"` - - `ImageURLContentBlock object { image_url, type }` + - `"regex"` - References an image URL in the content of a message. + - `type: "grammar"` - - `image_url: ImageURL` + Grammar format. Always `grammar`. - - `url: string` + - `"grammar"` - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `Namespace object { description, name, tools, type }` - - `detail: optional "auto" or "low" or "high"` + Groups function/custom tools under a shared namespace. - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + - `description: string` - - `"auto"` + A description of the namespace shown to the model. - - `"low"` + - `name: string` - - `"high"` + The namespace name used in tool calls (for example, `crm`). - - `type: "image_url"` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - The type of the content part. + The function/custom tools available inside this namespace. - - `"image_url"` + - `Function object { name, type, allowed_callers, 5 more }` - - `TextContentBlock object { text, type }` + - `name: string` - The text content that is part of a message. + - `type: "function"` - - `text: Text` + - `"function"` - - `annotations: array of Annotation` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` + The tool invocation context(s). - 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. + - `"direct"` - - `end_index: number` + - `"programmatic"` - - `file_citation: object { file_id }` + - `defer_loading: optional boolean` - - `file_id: string` + Whether this function should be deferred and discovered via tool search. - The ID of the specific File the citation is from. + - `description: optional string` - - `start_index: number` + - `output_schema: optional map[unknown]` - - `text: string` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - The text in the message content that needs to be replaced. + - `parameters: optional unknown` - - `type: "file_citation"` + - `strict: optional boolean` - Always `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. - - `"file_citation"` + - `Custom object { name, type, allowed_callers, 3 more }` - - `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + - `name: string` - - `end_index: number` + The name of the custom tool, used to identify it in tool calls. - - `file_path: object { file_id }` + - `type: "custom"` - - `file_id: string` + The type of the custom tool. Always `custom`. - The ID of the file that was generated. + - `"custom"` - - `start_index: number` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `text: string` + The tool invocation context(s). - The text in the message content that needs to be replaced. + - `"direct"` - - `type: "file_path"` + - `"programmatic"` - Always `file_path`. + - `defer_loading: optional boolean` - - `"file_path"` + Whether this tool should be deferred and discovered via tool search. - - `value: string` + - `description: optional string` - The data that makes up the text. + 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"` - Always `text`. + Unconstrained text format. Always `text`. - `"text"` - - `RefusalContentBlock object { refusal, type }` + - `Grammar object { definition, syntax, type }` - The refusal content generated by the assistant. + A grammar defined by the user. - - `refusal: string` + - `definition: string` - - `type: "refusal"` + The grammar definition. - Always `refusal`. + - `syntax: "lark" or "regex"` - - `"refusal"` + The syntax of the grammar definition. One of `lark` or `regex`. -### Message Content Delta + - `"lark"` -- `MessageContentDelta = ImageFileDeltaBlock or TextDeltaBlock or RefusalDeltaBlock or ImageURLDeltaBlock` + - `"regex"` - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + - `type: "grammar"` - - `ImageFileDeltaBlock object { index, type, image_file }` + Grammar format. Always `grammar`. - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + - `"grammar"` - - `index: number` + - `type: "namespace"` - The index of the content part in the message. + The type of the tool. Always `namespace`. - - `type: "image_file"` + - `"namespace"` - Always `image_file`. + - `ToolSearch object { type, description, execution, parameters }` - - `"image_file"` + Hosted or BYOT tool search configuration for deferred tools. - - `image_file: optional ImageFileDelta` + - `type: "tool_search"` - - `detail: optional "auto" or "low" or "high"` + The type of the tool. Always `tool_search`. - 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`. + - `"tool_search"` - - `"auto"` + - `description: optional string` - - `"low"` + Description shown to the model for a client-executed tool search tool. - - `"high"` + - `execution: optional "server" or "client"` - - `file_id: optional string` + Whether tool search is executed by the server or by the client. - The [File](https://platform.openai.com/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. + - `"server"` - - `TextDeltaBlock object { index, type, text }` + - `"client"` - The text content that is part of a message. + - `parameters: optional unknown` - - `index: number` + Parameter schema for a client-executed tool search tool. - The index of the content part in the message. + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - - `type: "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). - Always `text`. + - `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"` - - `text: optional TextDelta` + - `"image"` - - `annotations: optional array of AnnotationDelta` + - `search_context_size: optional "low" or "medium" or "high"` - - `FileCitationDeltaAnnotation object { index, type, end_index, 3 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. - 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. + - `"low"` - - `index: number` + - `"medium"` - The index of the annotation in the text content part. + - `"high"` - - `type: "file_citation"` + - `user_location: optional object { type, city, country, 2 more }` - Always `file_citation`. + The user's location. - - `"file_citation"` + - `type: "approximate"` - - `end_index: optional number` + The type of location approximation. Always `approximate`. - - `file_citation: optional object { file_id, quote }` + - `"approximate"` - - `file_id: optional string` + - `city: optional string` - The ID of the specific File the citation is from. + Free text input for the city of the user, e.g. `San Francisco`. - - `quote: optional string` + - `country: optional string` - The specific quote in the file. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `start_index: optional number` + - `region: optional string` - - `text: optional string` + Free text input for the region of the user, e.g. `California`. - The text in the message content that needs to be replaced. + - `timezone: optional string` - - `FilePathDeltaAnnotation object { index, type, end_index, 3 more }` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + - `ApplyPatch object { type, allowed_callers }` - - `index: number` + Allows the assistant to create, delete, or update files using unified diffs. - The index of the annotation in the text content part. + - `type: "apply_patch"` - - `type: "file_path"` + The type of the tool. Always `apply_patch`. - Always `file_path`. + - `"apply_patch"` - - `"file_path"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `end_index: optional number` + The tool invocation context(s). - - `file_path: optional object { file_id }` + - `"direct"` - - `file_id: optional string` + - `"programmatic"` - The ID of the file that was generated. + - `type: "additional_tools"` - - `start_index: optional number` + The item type. Always `additional_tools`. - - `text: optional string` + - `"additional_tools"` - The text in the message content that needs to be replaced. + - `id: optional string` - - `value: optional string` + The unique ID of this additional tools item. - The data that makes up the text. + - `agent: optional object { agent_name }` - - `RefusalDeltaBlock object { index, type, refusal }` + The agent that produced this item. - The refusal content that is part of a message. + - `agent_name: string` - - `index: number` + The canonical name of the agent that produced this item. - The index of the refusal part in the message. + - `Reasoning object { id, summary, type, 4 more }` - - `type: "refusal"` + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](/docs/guides/conversation-state). - Always `refusal`. + - `id: string` - - `"refusal"` + The unique identifier of the reasoning content. - - `refusal: optional string` + - `summary: array of object { text, type }` - - `ImageURLDeltaBlock object { index, type, image_url }` + Reasoning summary content. - References an image URL in the content of a message. + - `text: string` - - `index: number` + A summary of the reasoning output from the model so far. - The index of the content part in the message. + - `type: "summary_text"` - - `type: "image_url"` + The type of the object. Always `summary_text`. - Always `image_url`. + - `"summary_text"` - - `"image_url"` + - `type: "reasoning"` - - `image_url: optional ImageURLDelta` + The type of the object. Always `reasoning`. - - `detail: optional "auto" or "low" or "high"` + - `"reasoning"` - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. + - `agent: optional object { agent_name }` - - `"auto"` + The agent that produced this item. - - `"low"` + - `agent_name: string` - - `"high"` + The canonical name of the agent that produced this item. - - `url: optional string` + - `content: optional array of object { text, type }` - The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + Reasoning text content. -### Message Content Part Param + - `text: string` -- `MessageContentPartParam = ImageFileContentBlock or ImageURLContentBlock or TextContentBlockParam` + The reasoning text from the model. - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + - `type: "reasoning_text"` - - `ImageFileContentBlock object { image_file, type }` + The type of the reasoning text. Always `reasoning_text`. - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + - `"reasoning_text"` - - `image_file: ImageFile` + - `encrypted_content: optional string` - - `file_id: string` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - The [File](https://platform.openai.com/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: optional "in_progress" or "completed" or "incomplete"` - - `detail: optional "auto" or "low" or "high"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - 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`. + - `"in_progress"` - - `"auto"` + - `"completed"` - - `"low"` + - `"incomplete"` - - `"high"` + - `Compaction object { encrypted_content, type, id, agent }` - - `type: "image_file"` + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). - Always `image_file`. + - `encrypted_content: string` - - `"image_file"` + The encrypted content of the compaction summary. - - `ImageURLContentBlock object { image_url, type }` + - `type: "compaction"` - References an image URL in the content of a message. + The type of the item. Always `compaction`. - - `image_url: ImageURL` + - `"compaction"` - - `url: string` + - `id: optional string` - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + The ID of the compaction item. - - `detail: optional "auto" or "low" or "high"` + - `agent: optional object { agent_name }` - 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 agent that produced this item. - - `"auto"` + - `agent_name: string` - - `"low"` + The canonical name of the agent that produced this item. - - `"high"` + - `ImageGenerationCall object { id, result, status, 2 more }` - - `type: "image_url"` + An image generation request made by the model. - The type of the content part. + - `id: string` - - `"image_url"` + The unique ID of the image generation call. - - `TextContentBlockParam object { text, type }` + - `result: string` - The text content that is part of a message. + The generated image encoded in base64. - - `text: string` + - `status: "in_progress" or "completed" or "generating" or "failed"` - Text content to be sent to the model + The status of the image generation call. - - `type: "text"` + - `"in_progress"` - Always `text`. + - `"completed"` - - `"text"` + - `"generating"` -### Message Deleted + - `"failed"` -- `MessageDeleted object { id, deleted, object }` + - `type: "image_generation_call"` - - `id: string` + The type of the image generation call. Always `image_generation_call`. - - `deleted: boolean` + - `"image_generation_call"` - - `object: "thread.message.deleted"` + - `agent: optional object { agent_name }` - - `"thread.message.deleted"` + The agent that produced this item. -### Message Delta + - `agent_name: string` -- `MessageDelta object { content, role }` + The canonical name of the agent that produced this item. - The delta containing the fields that have changed on the Message. + - `CodeInterpreterCall object { id, code, container_id, 4 more }` - - `content: optional array of MessageContentDelta` + A tool call to run code. - The content of the message in array of text and/or images. + - `id: string` - - `ImageFileDeltaBlock object { index, type, image_file }` + The unique ID of the code interpreter tool call. - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + - `code: string` - - `index: number` + The code to run, or null if not available. - The index of the content part in the message. + - `container_id: string` - - `type: "image_file"` + The ID of the container used to run the code. - Always `image_file`. + - `outputs: array of object { logs, type } or object { type, url }` - - `"image_file"` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `image_file: optional ImageFileDelta` + - `Logs object { logs, type }` - - `detail: optional "auto" or "low" or "high"` + The logs output from the code interpreter. - 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 logs output from the code interpreter. - - `"low"` + - `type: "logs"` - - `"high"` + The type of the output. Always `logs`. - - `file_id: optional string` + - `"logs"` - The [File](https://platform.openai.com/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. + - `Image object { type, url }` - - `TextDeltaBlock object { index, type, text }` + The image output from the code interpreter. - The text content that is part of a message. + - `type: "image"` - - `index: number` + The type of the output. Always `image`. - The index of the content part in the message. + - `"image"` - - `type: "text"` + - `url: string` - Always `text`. + The URL of the image output from the code interpreter. - - `"text"` + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - - `text: optional TextDelta` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `annotations: optional array of AnnotationDelta` + - `"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. + - `"incomplete"` - - `index: number` + - `"interpreting"` - The index of the annotation in the text content part. + - `"failed"` - - `type: "file_citation"` + - `type: "code_interpreter_call"` - Always `file_citation`. + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `"file_citation"` + - `"code_interpreter_call"` - - `end_index: optional number` + - `agent: optional object { agent_name }` - - `file_citation: optional object { file_id, quote }` + The agent that produced this item. - - `file_id: optional string` + - `agent_name: string` - The ID of the specific File the citation is from. + The canonical name of the agent that produced this item. - - `quote: optional string` + - `LocalShellCall object { id, action, call_id, 3 more }` - The specific quote in the file. + A tool call to run a command on the local shell. - - `start_index: optional number` + - `id: string` - - `text: optional string` + The unique ID of the local shell call. - The text in the message content that needs to be replaced. + - `action: object { command, env, type, 3 more }` - - `FilePathDeltaAnnotation object { index, type, end_index, 3 more }` + Execute a shell command on the server. - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + - `command: array of string` - - `index: number` + The command to run. - The index of the annotation in the text content part. + - `env: map[string]` - - `type: "file_path"` + Environment variables to set for the command. - Always `file_path`. + - `type: "exec"` - - `"file_path"` + The type of the local shell action. Always `exec`. - - `end_index: optional number` + - `"exec"` - - `file_path: optional object { file_id }` + - `timeout_ms: optional number` - - `file_id: optional string` + Optional timeout in milliseconds for the command. - The ID of the file that was generated. + - `user: optional string` - - `start_index: optional number` + Optional user to run the command as. - - `text: optional string` + - `working_directory: optional string` - The text in the message content that needs to be replaced. + Optional working directory to run the command in. - - `value: optional string` + - `call_id: string` - The data that makes up the text. + The unique ID of the local shell tool call generated by the model. - - `RefusalDeltaBlock object { index, type, refusal }` + - `status: "in_progress" or "completed" or "incomplete"` - The refusal content that is part of a message. + The status of the local shell call. - - `index: number` + - `"in_progress"` - The index of the refusal part in the message. + - `"completed"` - - `type: "refusal"` + - `"incomplete"` - Always `refusal`. + - `type: "local_shell_call"` - - `"refusal"` + The type of the local shell call. Always `local_shell_call`. - - `refusal: optional string` + - `"local_shell_call"` - - `ImageURLDeltaBlock object { index, type, image_url }` + - `agent: optional object { agent_name }` - References an image URL in the content of a message. + The agent that produced this item. - - `index: number` + - `agent_name: string` - The index of the content part in the message. + The canonical name of the agent that produced this item. - - `type: "image_url"` + - `LocalShellCallOutput object { id, output, type, 2 more }` - Always `image_url`. + The output of a local shell tool call. - - `"image_url"` + - `id: string` - - `image_url: optional ImageURLDelta` + The unique ID of the local shell tool call generated by the model. - - `detail: optional "auto" or "low" or "high"` + - `output: string` - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. + A JSON string of the output of the local shell tool call. - - `"auto"` + - `type: "local_shell_call_output"` + + The type of the local shell tool call output. Always `local_shell_call_output`. + + - `"local_shell_call_output"` - - `"low"` + - `agent: optional object { agent_name }` - - `"high"` + The agent that produced this item. - - `url: optional string` + - `agent_name: string` - The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + The canonical name of the agent that produced this item. - - `role: optional "user" or "assistant"` + - `status: optional "in_progress" or "completed" or "incomplete"` - The entity that produced the message. One of `user` or `assistant`. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `"user"` + - `"in_progress"` - - `"assistant"` + - `"completed"` -### Message Delta Event + - `"incomplete"` -- `MessageDeltaEvent object { id, delta, object }` + - `ShellCall object { action, call_id, type, 5 more }` - Represents a message delta i.e. any changed fields on a message during streaming. + A tool representing a request to execute one or more shell commands. - - `id: string` + - `action: object { commands, max_output_length, timeout_ms }` - The identifier of the message, which can be referenced in API endpoints. + The shell commands and limits that describe how to run the tool call. - - `delta: MessageDelta` + - `commands: array of string` - The delta containing the fields that have changed on the Message. + Ordered shell commands for the execution environment to run. - - `content: optional array of MessageContentDelta` + - `max_output_length: optional number` - The content of the message in array of text and/or images. + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - - `ImageFileDeltaBlock object { index, type, image_file }` + - `timeout_ms: optional number` - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + Maximum wall-clock time in milliseconds to allow the shell commands to run. - - `index: number` + - `call_id: string` - The index of the content part in the message. + The unique ID of the shell tool call generated by the model. - - `type: "image_file"` + - `type: "shell_call"` - Always `image_file`. + The type of the item. Always `shell_call`. - - `"image_file"` + - `"shell_call"` - - `image_file: optional ImageFileDelta` + - `id: optional string` - - `detail: optional "auto" or "low" or "high"` + The unique ID of the shell tool call. Populated when this item is returned via API. - 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: optional object { agent_name }` - - `"auto"` + The agent that produced this item. - - `"low"` + - `agent_name: string` - - `"high"` + The canonical name of the agent that produced this item. - - `file_id: optional string` + - `caller: optional object { type } or object { caller_id, type }` - The [File](https://platform.openai.com/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 execution context that produced this tool call. - - `TextDeltaBlock object { index, type, text }` + - `Direct object { type }` - The text content that is part of a message. + - `type: "direct"` - - `index: number` + The caller type. Always `direct`. - The index of the content part in the message. + - `"direct"` - - `type: "text"` + - `Program object { caller_id, type }` - Always `text`. + - `caller_id: string` - - `"text"` + The call ID of the program item that produced this tool call. - - `text: optional TextDelta` + - `type: "program"` - - `annotations: optional array of AnnotationDelta` + The caller type. Always `program`. - - `FileCitationDeltaAnnotation object { index, type, end_index, 3 more }` + - `"program"` - 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. + - `environment: optional BetaLocalEnvironment or BetaContainerReference` - - `index: number` + The environment to execute the shell commands in. - The index of the annotation in the text content part. + - `BetaLocalEnvironment object { type, skills }` - - `type: "file_citation"` + - `BetaContainerReference object { container_id, type }` - Always `file_citation`. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"file_citation"` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `end_index: optional number` + - `"in_progress"` - - `file_citation: optional object { file_id, quote }` + - `"completed"` - - `file_id: optional string` + - `"incomplete"` - The ID of the specific File the citation is from. + - `ShellCallOutput object { call_id, output, type, 5 more }` - - `quote: optional string` + The streamed output items emitted by a shell tool call. - The specific quote in the file. + - `call_id: string` - - `start_index: optional number` + The unique ID of the shell tool call generated by the model. - - `text: optional string` + - `output: array of BetaResponseFunctionShellCallOutputContent` - The text in the message content that needs to be replaced. + Captured chunks of stdout and stderr output, along with their associated outcomes. - - `FilePathDeltaAnnotation object { index, type, end_index, 3 more }` + - `outcome: object { type } or object { exit_code, type }` - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + The exit or timeout outcome associated with this shell call. - - `index: number` + - `Timeout object { type }` - The index of the annotation in the text content part. + Indicates that the shell call exceeded its configured time limit. - - `type: "file_path"` + - `type: "timeout"` - Always `file_path`. + The outcome type. Always `timeout`. - - `"file_path"` + - `"timeout"` - - `end_index: optional number` + - `Exit object { exit_code, type }` - - `file_path: optional object { file_id }` + Indicates that the shell commands finished and returned an exit code. - - `file_id: optional string` + - `exit_code: number` - The ID of the file that was generated. + The exit code returned by the shell process. - - `start_index: optional number` + - `type: "exit"` - - `text: optional string` + The outcome type. Always `exit`. - The text in the message content that needs to be replaced. + - `"exit"` - - `value: optional string` + - `stderr: string` - The data that makes up the text. + Captured stderr output for the shell call. - - `RefusalDeltaBlock object { index, type, refusal }` + - `stdout: string` - The refusal content that is part of a message. + Captured stdout output for the shell call. - - `index: number` + - `type: "shell_call_output"` - The index of the refusal part in the message. + The type of the item. Always `shell_call_output`. - - `type: "refusal"` + - `"shell_call_output"` - Always `refusal`. + - `id: optional string` - - `"refusal"` + The unique ID of the shell tool call output. 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"` + - `max_output_length: optional number` - The entity that produced the message. One of `user` or `assistant`. + The maximum number of UTF-8 characters captured for this shell call's combined output. - - `"user"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"assistant"` + The status of the shell call output. - - `object: "thread.message.delta"` + - `"in_progress"` - The object type, which is always `thread.message.delta`. + - `"completed"` - - `"thread.message.delta"` + - `"incomplete"` -### Refusal Content Block + - `ApplyPatchCall object { call_id, operation, status, 4 more }` -- `RefusalContentBlock object { refusal, type }` + A tool call representing a request to create, delete, or update files using diff patches. - The refusal content generated by the assistant. + - `call_id: string` - - `refusal: string` + The unique ID of the apply patch tool call generated by the model. - - `type: "refusal"` + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - Always `refusal`. + The specific create, delete, or update instruction for the apply_patch tool call. - - `"refusal"` + - `CreateFile object { diff, path, type }` -### Refusal Delta Block + Instruction for creating a new file via the apply_patch tool. -- `RefusalDeltaBlock object { index, type, refusal }` + - `diff: string` - The refusal content that is part of a message. + Unified diff content to apply when creating the file. - - `index: number` + - `path: string` - The index of the refusal part in the message. + Path of the file to create relative to the workspace root. - - `type: "refusal"` + - `type: "create_file"` - Always `refusal`. + The operation type. Always `create_file`. - - `"refusal"` + - `"create_file"` - - `refusal: optional string` + - `DeleteFile object { path, type }` -### Text + Instruction for deleting an existing file via the apply_patch tool. -- `Text object { annotations, value }` + - `path: string` - - `annotations: array of Annotation` + Path of the file to delete relative to the workspace root. - - `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` + - `type: "delete_file"` - 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 operation type. Always `delete_file`. - - `end_index: number` + - `"delete_file"` - - `file_citation: object { file_id }` + - `UpdateFile object { diff, path, type }` - - `file_id: string` + Instruction for updating an existing file via the apply_patch tool. - The ID of the specific File the citation is from. + - `diff: string` - - `start_index: number` + Unified diff content to apply to the existing file. - - `text: string` + - `path: string` - The text in the message content that needs to be replaced. + Path of the file to update relative to the workspace root. - - `type: "file_citation"` + - `type: "update_file"` - Always `file_citation`. + The operation type. Always `update_file`. - - `"file_citation"` + - `"update_file"` - - `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` + - `status: "in_progress" or "completed"` - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `end_index: number` + - `"in_progress"` - - `file_path: object { file_id }` + - `"completed"` - - `file_id: string` + - `type: "apply_patch_call"` - The ID of the file that was generated. + The type of the item. Always `apply_patch_call`. - - `start_index: number` + - `"apply_patch_call"` - - `text: string` + - `id: optional string` - The text in the message content that needs to be replaced. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `type: "file_path"` + - `agent: optional object { agent_name }` - Always `file_path`. + The agent that produced this item. - - `"file_path"` + - `agent_name: string` - - `value: string` + The canonical name of the agent that produced this item. - The data that makes up the text. + - `caller: optional object { type } or object { caller_id, type }` -### Text Content Block + The execution context that produced this tool call. -- `TextContentBlock object { text, type }` + - `Direct object { type }` - The text content that is part of a message. + - `type: "direct"` - - `text: Text` + The caller type. Always `direct`. - - `annotations: array of Annotation` + - `"direct"` - - `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` + - `Program object { caller_id, 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. + - `caller_id: string` - - `end_index: number` + The call ID of the program item that produced this tool call. - - `file_citation: object { file_id }` + - `type: "program"` - - `file_id: string` + The caller type. Always `program`. - The ID of the specific File the citation is from. + - `"program"` - - `start_index: number` + - `ApplyPatchCallOutput object { call_id, status, type, 4 more }` - - `text: string` + The streamed output emitted by an apply patch tool call. - The text in the message content that needs to be replaced. + - `call_id: string` - - `type: "file_citation"` + The unique ID of the apply patch tool call generated by the model. - Always `file_citation`. + - `status: "completed" or "failed"` - - `"file_citation"` + The status of the apply patch tool call output. One of `completed` or `failed`. - - `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` + - `"completed"` - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + - `"failed"` - - `end_index: number` + - `type: "apply_patch_call_output"` - - `file_path: object { file_id }` + The type of the item. Always `apply_patch_call_output`. - - `file_id: string` + - `"apply_patch_call_output"` - The ID of the file that was generated. + - `id: optional string` - - `start_index: number` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `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"` + - `caller: optional object { type } or object { caller_id, type }` - - `value: string` + The execution context that produced this tool call. - The data that makes up the text. + - `Direct object { type }` - - `type: "text"` + - `type: "direct"` - Always `text`. + The caller type. Always `direct`. - - `"text"` + - `"direct"` -### Text Content Block Param + - `Program object { caller_id, type }` -- `TextContentBlockParam object { text, type }` + - `caller_id: string` - The text content that is part of a message. + The call ID of the program item that produced this tool call. - - `text: string` + - `type: "program"` - Text content to be sent to the model + The caller type. Always `program`. - - `type: "text"` + - `"program"` - Always `text`. + - `output: optional string` - - `"text"` + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). -### Text Delta + - `McpListTools object { id, server_label, tools, 3 more }` -- `TextDelta object { annotations, value }` + A list of tools available on an MCP server. - - `annotations: optional array of AnnotationDelta` + - `id: string` - - `FileCitationDeltaAnnotation object { index, type, end_index, 3 more }` + The unique ID of the list. - 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. + - `server_label: string` - - `index: number` + The label of the MCP server. - The index of the annotation in the text content part. + - `tools: array of object { input_schema, name, annotations, description }` - - `type: "file_citation"` + The tools available on the server. - Always `file_citation`. + - `input_schema: unknown` - - `"file_citation"` + The JSON schema describing the tool's input. - - `end_index: optional number` + - `name: string` - - `file_citation: optional object { file_id, quote }` + The name of the tool. - - `file_id: optional string` + - `annotations: optional unknown` - The ID of the specific File the citation is from. + Additional annotations about the tool. - - `quote: optional string` + - `description: optional string` - The specific quote in the file. + The description of the tool. - - `start_index: optional number` + - `type: "mcp_list_tools"` - - `text: optional string` + The type of the item. Always `mcp_list_tools`. - The text in the message content that needs to be replaced. + - `"mcp_list_tools"` - - `FilePathDeltaAnnotation object { index, type, end_index, 3 more }` + - `agent: optional object { agent_name }` - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + 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_path"` + - `error: optional string` - Always `file_path`. + Error message if the server could not list tools. - - `"file_path"` + - `McpApprovalRequest object { id, arguments, name, 3 more }` - - `end_index: optional number` + A request for human approval of a tool invocation. - - `file_path: optional object { file_id }` + - `id: string` - - `file_id: optional string` + The unique ID of the approval request. - The ID of the file that was generated. + - `arguments: string` - - `start_index: optional number` + A JSON string of arguments for the tool. - - `text: optional string` + - `name: string` - The text in the message content that needs to be replaced. + The name of the tool to run. - - `value: optional string` + - `server_label: string` - The data that makes up the text. + The label of the MCP server making the request. -### Text Delta Block + - `type: "mcp_approval_request"` -- `TextDeltaBlock object { index, type, text }` + The type of the item. Always `mcp_approval_request`. - The text content that is part of a message. + - `"mcp_approval_request"` - - `index: number` + - `agent: optional object { agent_name }` - The index of the content part in the message. + The agent that produced this item. - - `type: "text"` + - `agent_name: string` - Always `text`. + The canonical name of the agent that produced this item. - - `"text"` + - `McpApprovalResponse object { approval_request_id, approve, type, 3 more }` - - `text: optional TextDelta` + A response to an MCP approval request. - - `annotations: optional array of AnnotationDelta` + - `approval_request_id: string` - - `FileCitationDeltaAnnotation object { index, type, end_index, 3 more }` + The ID of the approval request being answered. - 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. + - `approve: boolean` - - `index: number` + Whether the request was approved. - The index of the annotation in the text content part. + - `type: "mcp_approval_response"` - - `type: "file_citation"` + The type of the item. Always `mcp_approval_response`. - Always `file_citation`. + - `"mcp_approval_response"` - - `"file_citation"` + - `id: optional string` - - `end_index: optional number` + The unique ID of the approval response - - `file_citation: optional object { file_id, quote }` + - `agent: optional object { agent_name }` - - `file_id: optional string` + The agent that produced this item. - The ID of the specific File the citation is from. + - `agent_name: string` - - `quote: optional string` + The canonical name of the agent that produced this item. - The specific quote in the file. + - `reason: optional string` - - `start_index: optional number` + Optional reason for the decision. - - `text: optional string` + - `McpCall object { id, arguments, name, 7 more }` - The text in the message content that needs to be replaced. + An invocation of a tool on an MCP server. - - `FilePathDeltaAnnotation object { index, type, end_index, 3 more }` + - `id: string` - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + The unique ID of the tool call. - - `index: number` + - `arguments: string` - The index of the annotation in the text content part. + A JSON string of the arguments passed to the tool. - - `type: "file_path"` + - `name: string` - Always `file_path`. + The name of the tool that was run. - - `"file_path"` + - `server_label: string` - - `end_index: optional number` + The label of the MCP server running the tool. - - `file_path: optional object { file_id }` + - `type: "mcp_call"` - - `file_id: optional string` + The type of the item. Always `mcp_call`. - The ID of the file that was generated. + - `"mcp_call"` - - `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` - - `value: optional string` + The canonical name of the agent that produced this item. - The data that makes up the text. + - `approval_request_id: optional string` -# Responses + 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. -## Create a model response + - `error: optional string` -**post** `/responses?beta=true` + The error from the tool call, if any. -Create a model response + - `output: optional string` -### Header Parameters + The output from the tool call. -- `"openai-beta": optional array of "responses_multi_agent=v1"` + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - - `"responses_multi_agent=v1"` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. -### Body Parameters + - `"in_progress"` -- `background: optional boolean` + - `"completed"` - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + - `"incomplete"` -- `context_management: optional array of object { type, compact_threshold }` + - `"calling"` - Context management configuration for this request. + - `"failed"` - - `type: string` + - `CustomToolCallOutput object { call_id, output, type, 3 more }` - The context management entry type. Currently only 'compaction' is supported. + The output of a custom tool call from your code, being sent back to the model. - - `compact_threshold: optional number` + - `call_id: string` - Token threshold at which compaction should be triggered for this entry. + The call ID, used to map this custom tool call output to a custom tool call. -- `conversation: optional string or BetaResponseConversationParam` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - 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. + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `ConversationID = string` + - `StringOutput = string` - The unique ID of the conversation. + A string of the output of the custom tool call. - - `BetaResponseConversationParam object { id }` + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - The conversation that this response belongs to. + Text, image, or file output of the custom tool call. - - `id: string` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - The unique ID of the conversation. + A text input to the model. -- `include: optional array of BetaResponseIncludable` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - Specify additional output data to include in the model response. Currently supported values are: + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `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). + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `"file_search_call.results"` + A file input to the model. - - `"web_search_call.results"` + - `type: "custom_tool_call_output"` - - `"web_search_call.action.sources"` + The type of the custom tool call output. Always `custom_tool_call_output`. - - `"message.input_image.image_url"` + - `"custom_tool_call_output"` - - `"computer_call_output.output.image_url"` + - `id: optional string` - - `"code_interpreter_call.outputs"` + The unique ID of the custom tool call output in the OpenAI platform. - - `"reasoning.encrypted_content"` + - `agent: optional object { agent_name }` - - `"message.output_text.logprobs"` + The agent that produced this item. -- `input: optional string or BetaResponseInput` + - `agent_name: string` - Text, image, or file inputs to the model, used to generate a response. + The canonical name of the agent that produced this item. - Learn more: + - `caller: optional object { type } or object { caller_id, type }` - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Image inputs](https://platform.openai.com/docs/guides/images) - - [File inputs](https://platform.openai.com/docs/guides/pdf-files) - - [Conversation state](https://platform.openai.com/docs/guides/conversation-state) - - [Function calling](https://platform.openai.com/docs/guides/function-calling) + The execution context that produced this tool call. - - `TextInput = string` + - `Direct object { type }` - A text input to the model, equivalent to a text input with the - `user` role. + - `type: "direct"` - - `BetaResponseInput = array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + The caller type. Always `direct`. - A list of one or many input items to the model, containing - different content types. + - `"direct"` - - `BetaEasyInputMessage object { content, role, phase, type }` + - `Program object { caller_id, 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. + - `caller_id: string` - - `content: string or BetaResponseInputMessageContentList` + The call ID of the program item that produced this tool call. - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + - `type: "program"` - - `TextInput = string` + The caller type. Always `program`. - A text input to the model. + - `"program"` - - `BetaResponseInputMessageContentList = array of BetaResponseInputContent` + - `CustomToolCall object { call_id, input, name, 5 more }` - A list of one or many input items to the model, containing different content - types. + A call to a custom tool created by the model. - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `call_id: string` - A text input to the model. + An identifier used to map this custom tool call to a tool call output. - - `text: string` + - `input: string` - The text input to the model. + The input for the custom tool call generated by the model. - - `type: "input_text"` + - `name: string` - The type of the input item. Always `input_text`. + The name of the custom tool being called. - - `"input_text"` + - `type: "custom_tool_call"` - - `prompt_cache_breakpoint: optional object { mode }` + The type of the custom tool call. Always `custom_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. + - `"custom_tool_call"` - - `mode: "explicit"` + - `id: optional string` - The breakpoint mode. Always `explicit`. + The unique ID of the custom tool call in the OpenAI platform. - - `"explicit"` + - `agent: optional object { agent_name }` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + The agent that produced this item. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `agent_name: string` - - `detail: "low" or "high" or "auto" or "original"` + The canonical name of the agent that produced this item. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `caller: optional object { type } or object { caller_id, type }` - - `"low"` + The execution context that produced this tool call. - - `"high"` + - `Direct object { type }` - - `"auto"` + - `type: "direct"` - - `"original"` + - `"direct"` - - `type: "input_image"` + - `Program object { caller_id, type }` - The type of the input item. Always `input_image`. + - `caller_id: string` - - `"input_image"` + The call ID of the program item that produced this tool call. - - `file_id: optional string` + - `type: "program"` - The ID of the file to be sent to the model. + - `"program"` - - `image_url: optional string` + - `namespace: 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 namespace of the custom tool being called. - - `prompt_cache_breakpoint: optional object { mode }` + - `CompactionTrigger object { type, 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. + Compacts the current context. Must be the final input item. - - `mode: "explicit"` + - `type: "compaction_trigger"` - The breakpoint mode. Always `explicit`. + The type of the item. Always `compaction_trigger`. - - `"explicit"` + - `"compaction_trigger"` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `agent: optional object { agent_name }` - A file input to the model. + The agent that produced this item. - - `type: "input_file"` + - `agent_name: string` - The type of the input item. Always `input_file`. + The canonical name of the agent that produced this item. - - `"input_file"` + - `ItemReference object { id, agent, type }` - - `detail: optional "auto" or "low" or "high"` + An internal identifier for an item to reference. - 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 ID of the item to reference. - - `"low"` + - `agent: optional object { agent_name }` - - `"high"` + The agent that produced this item. - - `file_data: optional string` + - `agent_name: string` - The content of the file to be sent to the model. + The canonical name of the agent that produced this item. - - `file_id: optional string` + - `type: optional "item_reference"` - The ID of the file to be sent to the model. + The type of item to reference. Always `item_reference`. - - `file_url: optional string` + - `"item_reference"` - The URL of the file to be sent to the model. + - `Program object { id, call_id, code, 3 more }` - - `filename: optional string` + - `id: string` - The name of the file to be sent to the model. + The unique ID of this program item. - - `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 stable call ID of the program item. - - `mode: "explicit"` + - `code: string` - The breakpoint mode. Always `explicit`. + The JavaScript source executed by programmatic tool calling. - - `"explicit"` + - `fingerprint: string` - - `role: "user" or "assistant" or "system" or "developer"` + Opaque program replay fingerprint that must be round-tripped. - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + - `type: "program"` - - `"user"` + The item type. Always `program`. - - `"assistant"` + - `"program"` - - `"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"` + - `ProgramOutput object { id, call_id, result, 3 more }` - - `"final_answer"` + - `id: string` - - `type: optional "message"` + The unique ID of this program output item. - The type of the message input. Always `message`. + - `call_id: string` - - `"message"` + The call ID of the program item. - - `Message object { content, role, agent, 2 more }` + - `result: 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 result produced by the program item. - - `content: BetaResponseInputMessageContentList` + - `status: "completed" or "incomplete"` - A list of one or many input items to the model, containing different content - types. + The terminal status of the program output. - - `role: "user" or "system" or "developer"` + - `"completed"` - The role of the message input. One of `user`, `system`, or `developer`. + - `"incomplete"` - - `"user"` + - `type: "program_output"` - - `"system"` + The item type. Always `program_output`. - - `"developer"` + - `"program_output"` - `agent: optional object { agent_name }` @@ -21405,224 +23297,246 @@ Create a model response 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, text, type, logprobs }` + - `"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"` - - `text: string` + - `"codex-mini-latest"` - The text output from the model. + - `"gpt-4o-mini"` - - `type: "output_text"` + - `"gpt-4o-mini-2024-07-18"` - The type of the output text. Always `output_text`. + - `"gpt-4-turbo"` - - `"output_text"` + - `"gpt-4-turbo-2024-04-09"` - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + - `"gpt-4-0125-preview"` - - `token: string` + - `"gpt-4-turbo-preview"` - - `bytes: array of number` + - `"gpt-4-1106-preview"` - - `logprob: number` + - `"gpt-4-vision-preview"` - - `top_logprobs: array of object { token, bytes, logprob }` + - `"gpt-4"` - - `token: string` + - `"gpt-4-0314"` - - `bytes: array of number` + - `"gpt-4-0613"` - - `logprob: number` + - `"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` + + - `object: "response"` + + The object type of this resource - always set to `response`. + + - `"response"` + + - `output: array of BetaResponseOutputItem` + + An array of content items generated by the model. - - `"commentary"` + - 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. - - `"final_answer"` + - `BetaResponseOutputMessage object { id, content, role, 4 more }` + + An output message from the model. - `FileSearchCall object { id, queries, status, 3 more }` The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + [file search guide](/docs/guides/tools-file-search) for more information. - `id: string` @@ -21695,36 +23609,66 @@ Create a model response 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](https://platform.openai.com/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. @@ -21735,247 +23679,273 @@ Create a model response - `"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 }` @@ -21985,58 +23955,55 @@ Create a model response 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 }` @@ -22046,20 +24013,10 @@ Create a model response 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](https://platform.openai.com/docs/guides/tools-web-search) for more information. + [web search guide](/docs/guides/tools-web-search) for more information. - `id: string` @@ -22160,66 +24117,36 @@ Create a model response 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](https://platform.openai.com/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. @@ -22230,145 +24157,121 @@ Create a model response - `"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 BetaResponseFunctionCallOutputItemList` - - Text, image, or file output of the function tool call. - - - `string` - - A JSON string of the output of the function tool call. - - - `BetaResponseFunctionCallOutputItemList = array of BetaResponseFunctionCallOutputItem` - - 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`. + - `type: "computer_call"` - - `"input_text"` + The type of the computer call. Always `computer_call`. - - `prompt_cache_breakpoint: optional object { mode }` + - `"computer_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. + - `action: optional BetaComputerAction` - - `mode: "explicit"` + A click action. - The breakpoint mode. Always `explicit`. + - `actions: optional BetaComputerActionList` - - `"explicit"` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` + - `agent: optional object { agent_name }` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + 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"` + - `ComputerCallOutput object { id, call_id, output, 5 more }` - - `detail: optional "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 computer call tool output. - - `"low"` + - `call_id: string` - - `"high"` + The ID of the computer tool call that produced the output. - - `"auto"` + - `output: BetaResponseComputerToolCallOutputScreenshot` - - `"original"` + A computer screenshot image used with the computer use tool. - - `file_id: optional string` + - `status: "completed" or "incomplete" or "failed" or "in_progress"` - The ID of the file to be sent to the model. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `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 }` + - `"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. + - `"in_progress"` - - `mode: "explicit"` + - `type: "computer_call_output"` - The breakpoint mode. Always `explicit`. + The type of the computer tool call output. Always `computer_call_output`. - - `"explicit"` + - `"computer_call_output"` - - `BetaResponseInputFileContent object { type, detail, file_data, 4 more }` + - `acknowledged_safety_checks: optional array of object { id, code, message }` - A file input to the model. + The safety checks reported by the API that have been acknowledged by the + developer. - - `type: "input_file"` + - `id: string` - The type of the input item. Always `input_file`. + The ID of the pending safety check. - - `"input_file"` + - `code: optional string` - - `detail: optional "auto" or "low" or "high"` + The type of the pending safety check. - 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`. + - `message: optional string` - - `"auto"` + Details about the pending safety check. - - `"low"` + - `agent: optional object { agent_name }` - - `"high"` + The agent that produced this item. - - `file_data: optional string` + - `agent_name: string` - The base64-encoded data of the file to be sent to the model. + The canonical name of the agent that produced this item. - - `file_id: optional string` + - `created_by: optional string` - The ID of the file to be sent to the model. + The identifier of the actor that created the item. - - `file_url: optional string` + - `Reasoning object { id, summary, type, 4 more }` - The URL of the file to be sent to 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). - - `filename: optional string` + - `id: string` - The name of the file to be sent to the model. + The unique identifier of the reasoning content. - - `prompt_cache_breakpoint: optional object { mode }` + - `summary: array of object { text, 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. + Reasoning summary content. - - `mode: "explicit"` + - `text: string` - The breakpoint mode. Always `explicit`. + A summary of the reasoning output from the model so far. - - `"explicit"` + - `type: "summary_text"` - - `type: "function_call_output"` + The type of the object. Always `summary_text`. - The type of the function tool call output. Always `function_call_output`. + - `"summary_text"` - - `"function_call_output"` + - `type: "reasoning"` - - `id: optional string` + The type of the object. Always `reasoning`. - The unique ID of the function tool call output. Populated when this item is returned via API. + - `"reasoning"` - `agent: optional object { agent_name }` @@ -22378,33 +24281,29 @@ Create a model response 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"` + - `content: optional array of object { text, type }` - The caller type. Always `direct`. + Reasoning text content. - - `"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"` - The caller type. Always `program`. + - `encrypted_content: optional string` - - `"program"` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - `status: optional "in_progress" or "completed" or "incomplete"` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `"in_progress"` @@ -22412,53 +24311,29 @@ Create a model response - `"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](https://platform.openai.com/docs/guides/vision) - - - `EncryptedContent object { encrypted_content, type }` - - Opaque encrypted content that Responses API decrypts inside trusted model execution. - - - `encrypted_content: string` + - `Program object { id, call_id, code, 3 more }` - Opaque encrypted content. + - `id: string` - - `type: "encrypted_content"` + The unique ID of the program item. - The type of the input item. Always `encrypted_content`. + - `call_id: string` - - `"encrypted_content"` + The stable call ID of the program item. - - `recipient: string` + - `code: string` - The destination agent identity. + The JavaScript source executed by programmatic tool calling. - - `type: "agent_message"` + - `fingerprint: string` - The item type. Always `agent_message`. + Opaque program replay fingerprint that must be round-tripped. - - `"agent_message"` + - `type: "program"` - - `id: optional string` + The type of the item. Always `program`. - The unique ID of this agent message item. + - `"program"` - `agent: optional object { agent_name }` @@ -22468,41 +24343,33 @@ Create a model response 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"` + - `ProgramOutput object { id, call_id, result, 3 more }` - - `"list_agents"` + - `id: string` - - `"send_message"` + The unique ID of the program output item. - - `"followup_task"` + - `call_id: string` - - `"wait_agent"` + The call ID of the program item. - - `arguments: string` + - `result: string` - The action arguments as a JSON string. + The result produced by the program item. - - `call_id: string` + - `status: "completed" or "incomplete"` - The unique ID linking this call to its output. + The terminal status of the program output item. - - `type: "multi_agent_call"` + - `"completed"` - The item type. Always `multi_agent_call`. + - `"incomplete"` - - `"multi_agent_call"` + - `type: "program_output"` - - `id: optional string` + The type of the item. Always `program_output`. - The unique ID of this multi-agent call. + - `"program_output"` - `agent: optional object { agent_name }` @@ -22512,127 +24379,43 @@ Create a model response 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"` + - `ToolSearchCall object { id, arguments, call_id, 5 more }` - - `"list_agents"` + - `id: string` - - `"send_message"` + The unique ID of the tool search call item. - - `"followup_task"` + - `arguments: unknown` - - `"wait_agent"` + Arguments used for the tool search call. - `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 array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` - - Citations associated with the text content. - - - `array of 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"` - - - `array of 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. - - - `array of 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. + The unique ID of the tool search call generated by the model. - - `filename: string` + - `execution: "server" or "client"` - The filename of the container file cited. + Whether tool search was executed by the server or by the client. - - `start_index: number` + - `"server"` - The index of the first character of the citation in the message. + - `"client"` - - `type: "container_file_citation"` + - `status: "in_progress" or "completed" or "incomplete"` - The citation type. Always `container_file_citation`. + The status of the tool search call item that was recorded. - - `"container_file_citation"` + - `"in_progress"` - - `type: "multi_agent_call_output"` + - `"completed"` - The item type. Always `multi_agent_call_output`. + - `"incomplete"` - - `"multi_agent_call_output"` + - `type: "tool_search_call"` - - `id: optional string` + The type of the item. Always `tool_search_call`. - The unique ID of this multi-agent call output. + - `"tool_search_call"` - `agent: optional object { agent_name }` @@ -22642,35 +24425,21 @@ Create a model 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. - - - `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. + - `created_by: optional string` - - `agent: optional object { agent_name }` + The identifier of the actor that created the item. - The agent that produced this item. + - `ToolSearchOutput object { id, call_id, execution, 5 more }` - - `agent_name: string` + - `id: string` - The canonical name of the agent that produced this item. + The unique ID of the tool search output item. - - `call_id: optional string` + - `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. @@ -22678,9 +24447,9 @@ Create a model response - `"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"` @@ -22688,11 +24457,9 @@ Create a model response - `"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 }` @@ -22955,7 +24722,7 @@ Create a model response - `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](https://platform.openai.com/docs/guides/tools-web-search). + [web search tool](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -23015,7 +24782,7 @@ Create a model response - `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](https://platform.openai.com/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -23067,7 +24834,7 @@ Create a model response 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -23213,40 +24980,8 @@ Create a model response - `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`. @@ -23291,19 +25026,8 @@ Create a model response - `background: optional "transparent" or "opaque" or "auto"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. - - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. - - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - `"transparent"` @@ -23332,13 +25056,13 @@ Create a model response Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `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-2" or 3 more` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` The image generation model to use. Default: `gpt-image-1`. @@ -23346,14 +25070,8 @@ Create a model response - `"gpt-image-1-mini"` - - `"gpt-image-2"` - - - `"gpt-image-2-2026-04-21"` - - `"gpt-image-1.5"` - - `"chatgpt-image-latest"` - - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -23444,131 +25162,13 @@ Create a model response - `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](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -23682,7 +25282,7 @@ Create a model response - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -23852,14 +25452,10 @@ Create a model response - `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. @@ -23868,39 +25464,39 @@ Create a model response 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 }` @@ -24163,7 +25759,7 @@ Create a model response - `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](https://platform.openai.com/docs/guides/tools-web-search). + [web search tool](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -24223,7 +25819,7 @@ Create a model response - `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](https://platform.openai.com/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -24275,7 +25871,7 @@ Create a model response 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -24467,19 +26063,8 @@ Create a model response - `background: optional "transparent" or "opaque" or "auto"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. - - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. - - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - `"transparent"` @@ -24508,13 +26093,13 @@ Create a model response Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `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-2" or 3 more` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` The image generation model to use. Default: `gpt-image-1`. @@ -24522,14 +26107,8 @@ Create a model response - `"gpt-image-1-mini"` - - `"gpt-image-2"` - - - `"gpt-image-2-2026-04-21"` - - `"gpt-image-1.5"` - - `"chatgpt-image-latest"` - - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -24626,7 +26205,7 @@ Create a model response - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -24740,7 +26319,7 @@ Create a model response - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -24910,14 +26489,10 @@ Create a model response - `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. @@ -24926,82 +26501,17 @@ Create a model response 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](https://platform.openai.com/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 - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. - - - `status: optional "in_progress" or "completed" or "incomplete"` - - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `Compaction object { encrypted_content, type, id, agent }` - - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/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"` @@ -25009,10 +26519,6 @@ Create a model response - `"compaction"` - - `id: optional string` - - The ID of the compaction item. - - `agent: optional object { agent_name }` The agent that produced this item. @@ -25021,6 +26527,10 @@ Create a model response 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. @@ -25238,9 +26748,13 @@ Create a model response - `"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 }` @@ -25248,71 +26762,45 @@ Create a model response - `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. - - `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"` + - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` - The caller type. Always `direct`. + Represents the use of a local environment to perform shell actions. - - `"direct"` + - `BetaResponseLocalEnvironment object { type }` - - `Program object { caller_id, type }` + Represents the use of a local environment to perform shell actions. - - `caller_id: string` + - `type: "local"` - The call ID of the program item that produced this tool call. + The environment type. Always `local`. - - `type: "program"` + - `"local"` - The caller type. Always `program`. + - `BetaResponseContainerReference object { container_id, type }` - - `"program"` + Represents a container created with /v1/containers. - - `environment: optional BetaLocalEnvironment or BetaContainerReference` + - `container_id: string` - The environment to execute the shell commands in. + - `type: "container_reference"` - - `BetaLocalEnvironment object { type, skills }` + The environment type. Always `container_reference`. - - `BetaContainerReference object { container_id, type }` + - `"container_reference"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `status: "in_progress" or "completed" or "incomplete"` The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. @@ -25322,563 +26810,11 @@ Create a model response - `"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](https://platform.openai.com/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"` + - `type: "shell_call"` - - `id: optional string` + The type of the item. Always `shell_call`. - The unique ID of the custom tool call in the OpenAI platform. + - `"shell_call"` - `agent: optional object { agent_name }` @@ -25908,109 +26844,85 @@ Create a model response - `"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` + - `created_by: optional string` - The canonical name of the agent that produced this item. + The ID of the entity that created this tool call. - - `ItemReference object { id, agent, type }` + - `ShellCallOutput object { id, call_id, max_output_length, 6 more }` - An internal identifier for an item to reference. + The output of a shell tool call that was emitted. - `id: string` - The ID of the item to reference. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` + The unique ID of the shell call output. Populated when this item is returned via API. - The canonical name of the agent that produced this item. + - `call_id: string` - - `type: optional "item_reference"` + The unique ID of the shell tool call generated by the model. - The type of item to reference. Always `item_reference`. + - `max_output_length: number` - - `"item_reference"` + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - `Program object { id, call_id, code, 3 more }` + - `output: array of object { outcome, stderr, stdout, created_by }` - - `id: string` + An array of shell call output contents - The unique ID of this program item. + - `outcome: object { type } or object { exit_code, type }` - - `call_id: string` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - The stable call ID of the program item. + - `Timeout object { type }` - - `code: string` + Indicates that the shell call exceeded its configured time limit. - The JavaScript source executed by programmatic tool calling. + - `type: "timeout"` - - `fingerprint: string` + The outcome type. Always `timeout`. - Opaque program replay fingerprint that must be round-tripped. + - `"timeout"` - - `type: "program"` + - `Exit object { exit_code, type }` - The item type. Always `program`. + Indicates that the shell commands finished and returned an exit code. - - `"program"` + - `exit_code: number` - - `agent: optional object { agent_name }` + Exit code from the shell process. - The agent that produced this item. + - `type: "exit"` - - `agent_name: string` + The outcome type. Always `exit`. - The canonical name of the agent that produced this item. + - `"exit"` - - `ProgramOutput object { id, call_id, result, 3 more }` + - `stderr: string` - - `id: string` + The standard error output that was captured. - The unique ID of this program output item. + - `stdout: string` - - `call_id: string` + The standard output that was captured. - The call ID of the program item. + - `created_by: optional string` - - `result: string` + The identifier of the actor that created the item. - The result produced by the program item. + - `status: "in_progress" or "completed" or "incomplete"` - - `status: "completed" or "incomplete"` + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - The terminal status of the program output. + - `"in_progress"` - `"completed"` - `"incomplete"` - - `type: "program_output"` + - `type: "shell_call_output"` - The item type. Always `program_output`. + The type of the shell call output. Always `shell_call_output`. - - `"program_output"` + - `"shell_call_output"` - `agent: optional object { agent_name }` @@ -26020,606 +26932,539 @@ Create a model response The canonical name of the agent that produced this item. -- `instructions: optional string` - - A system (or developer) message inserted into the model's context. + - `caller: optional object { type } or object { caller_id, 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 execution context that produced this tool call. -- `max_output_tokens: optional number` + - `Direct object { type }` - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + - `type: "direct"` -- `max_tool_calls: optional number` + - `"direct"` - 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. + - `Program object { caller_id, type }` -- `metadata: optional map[string]` + - `caller_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 call ID of the program item that produced this tool call. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `type: "program"` -- `model: optional "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` + - `"program"` - 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](https://platform.openai.com/docs/models) - to browse and compare available models. + - `created_by: optional string` - - `"gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more` + The identifier of the actor that created the item. - 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](https://platform.openai.com/docs/models) - to browse and compare available models. + - `ApplyPatchCall object { id, call_id, operation, 5 more }` - - `"gpt-5.6-sol"` + A tool call that applies file diffs by creating, deleting, or updating files. - - `"gpt-5.6-terra"` + - `id: string` - - `"gpt-5.6-luna"` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `"gpt-5.4"` + - `call_id: string` - - `"gpt-5.4-mini"` + The unique ID of the apply patch tool call generated by the model. - - `"gpt-5.4-nano"` + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - - `"gpt-5.4-mini-2026-03-17"` + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `"gpt-5.4-nano-2026-03-17"` + - `CreateFile object { diff, path, type }` - - `"gpt-5.3-chat-latest"` + Instruction describing how to create a file via the apply_patch tool. - - `"gpt-5.2"` + - `diff: string` - - `"gpt-5.2-2025-12-11"` + Diff to apply. - - `"gpt-5.2-chat-latest"` + - `path: string` - - `"gpt-5.2-pro"` + Path of the file to create. - - `"gpt-5.2-pro-2025-12-11"` + - `type: "create_file"` - - `"gpt-5.1"` + Create a new file with the provided diff. - - `"gpt-5.1-2025-11-13"` + - `"create_file"` - - `"gpt-5.1-codex"` + - `DeleteFile object { path, type }` - - `"gpt-5.1-mini"` + Instruction describing how to delete a file via the apply_patch tool. - - `"gpt-5.1-chat-latest"` + - `path: string` - - `"gpt-5"` + Path of the file to delete. - - `"gpt-5-mini"` + - `type: "delete_file"` - - `"gpt-5-nano"` + Delete the specified file. - - `"gpt-5-2025-08-07"` + - `"delete_file"` - - `"gpt-5-mini-2025-08-07"` + - `UpdateFile object { diff, path, type }` - - `"gpt-5-nano-2025-08-07"` + Instruction describing how to update a file via the apply_patch tool. - - `"gpt-5-chat-latest"` + - `diff: string` - - `"gpt-4.1"` + Diff to apply. - - `"gpt-4.1-mini"` + - `path: string` - - `"gpt-4.1-nano"` + Path of the file to update. - - `"gpt-4.1-2025-04-14"` + - `type: "update_file"` - - `"gpt-4.1-mini-2025-04-14"` + Update an existing file with the provided diff. - - `"gpt-4.1-nano-2025-04-14"` + - `"update_file"` - - `"o4-mini"` + - `status: "in_progress" or "completed"` - - `"o4-mini-2025-04-16"` + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `"o3"` + - `"in_progress"` - - `"o3-2025-04-16"` + - `"completed"` - - `"o3-mini"` + - `type: "apply_patch_call"` - - `"o3-mini-2025-01-31"` + The type of the item. Always `apply_patch_call`. - - `"o1"` + - `"apply_patch_call"` - - `"o1-2024-12-17"` + - `agent: optional object { agent_name }` - - `"o1-preview"` + The agent that produced this item. - - `"o1-preview-2024-09-12"` + - `agent_name: string` - - `"o1-mini"` + The canonical name of the agent that produced this item. - - `"o1-mini-2024-09-12"` + - `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"` + - `"direct"` - - `"gpt-4o-audio-preview"` + - `Program object { caller_id, type }` - - `"gpt-4o-audio-preview-2024-10-01"` + - `caller_id: string` - - `"gpt-4o-audio-preview-2024-12-17"` + The call ID of the program item that produced this tool call. - - `"gpt-4o-audio-preview-2025-06-03"` + - `type: "program"` - - `"gpt-4o-mini-audio-preview"` + - `"program"` - - `"gpt-4o-mini-audio-preview-2024-12-17"` + - `created_by: optional string` - - `"gpt-4o-search-preview"` + The ID of the entity that created this tool call. - - `"gpt-4o-mini-search-preview"` + - `ApplyPatchCallOutput object { id, call_id, status, 5 more }` - - `"gpt-4o-search-preview-2025-03-11"` + The output emitted by an apply patch tool call. - - `"gpt-4o-mini-search-preview-2025-03-11"` + - `id: string` - - `"chatgpt-4o-latest"` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `"codex-mini-latest"` + - `call_id: string` - - `"gpt-4o-mini"` + The unique ID of the apply patch tool call generated by the model. - - `"gpt-4o-mini-2024-07-18"` + - `status: "completed" or "failed"` - - `"gpt-4-turbo"` + The status of the apply patch tool call output. One of `completed` or `failed`. - - `"gpt-4-turbo-2024-04-09"` + - `"completed"` - - `"gpt-4-0125-preview"` + - `"failed"` - - `"gpt-4-turbo-preview"` + - `type: "apply_patch_call_output"` - - `"gpt-4-1106-preview"` + The type of the item. Always `apply_patch_call_output`. - - `"gpt-4-vision-preview"` + - `"apply_patch_call_output"` - - `"gpt-4"` + - `agent: optional object { agent_name }` - - `"gpt-4-0314"` + The agent that produced this item. - - `"gpt-4-0613"` + - `agent_name: string` - - `"gpt-4-32k"` + The canonical name of the agent that produced this item. - - `"gpt-4-32k-0314"` + - `caller: optional object { type } or object { caller_id, type }` - - `"gpt-4-32k-0613"` + The execution context that produced this tool call. - - `"gpt-3.5-turbo"` + - `Direct object { type }` - - `"gpt-3.5-turbo-16k"` + - `type: "direct"` - - `"gpt-3.5-turbo-0301"` + - `"direct"` - - `"gpt-3.5-turbo-0613"` + - `Program object { caller_id, type }` - - `"gpt-3.5-turbo-1106"` + - `caller_id: string` - - `"gpt-3.5-turbo-0125"` + The call ID of the program item that produced this tool call. - - `"gpt-3.5-turbo-16k-0613"` + - `type: "program"` - - `"o1-pro"` + - `"program"` - - `"o1-pro-2025-03-19"` + - `created_by: optional string` - - `"o3-pro"` + The ID of the entity that created this tool call output. - - `"o3-pro-2025-06-10"` + - `output: optional string` - - `"o3-deep-research"` + Optional textual output returned by the apply patch tool. - - `"o3-deep-research-2025-06-26"` + - `McpCall object { id, arguments, name, 7 more }` - - `"o4-mini-deep-research"` + An invocation of a tool on an MCP server. - - `"o4-mini-deep-research-2025-06-26"` + - `id: string` - - `"computer-use-preview"` + The unique ID of the tool call. - - `"computer-use-preview-2025-03-11"` + - `arguments: string` - - `"gpt-5-codex"` + A JSON string of the arguments passed to the tool. - - `"gpt-5-pro"` + - `name: string` - - `"gpt-5-pro-2025-10-06"` + The name of the tool that was run. - - `"gpt-5.1-codex-max"` + - `server_label: string` - - `string` + The label of the MCP server running the tool. -- `moderation: optional object { model, policy }` + - `type: "mcp_call"` - Configuration for running moderation on the input and output of this response. + The type of the item. Always `mcp_call`. - - `model: string` + - `"mcp_call"` - The moderation model to use for moderated completions, e.g. 'omni-moderation-latest'. + - `agent: optional object { agent_name }` - - `policy: optional object { input, output }` + The agent that produced this item. - The policy to apply to moderated response input and output. + - `agent_name: string` - - `input: optional object { mode }` + The canonical name of the agent that produced this item. - The moderation policy for the response input. + - `approval_request_id: optional string` - - `mode: "score" or "block"` + 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. - - `"score"` + - `error: optional string` - - `"block"` + The error from the tool call, if any. - - `output: optional object { mode }` + - `output: optional string` - The moderation policy for the response output. + The output from the tool call. - - `mode: "score" or "block"` + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - - `"score"` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `"block"` + - `"in_progress"` -- `multi_agent: optional object { enabled, max_concurrent_subagents }` + - `"completed"` - Configuration for server-hosted multi-agent execution. + - `"incomplete"` - - `enabled: boolean` + - `"calling"` - Whether to enable server-hosted multi-agent execution for this response. + - `"failed"` - - `max_concurrent_subagents: optional number` + - `McpListTools object { id, server_label, tools, 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. + A list of tools available on an MCP server. -- `parallel_tool_calls: optional boolean` + - `id: string` - Whether to allow the model to run tool calls in parallel. + The unique ID of the list. -- `previous_response_id: optional string` + - `server_label: string` - The unique ID of the previous response to the model. Use this to - create multi-turn conversations. Learn more about - [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + The label of the MCP server. -- `prompt: optional BetaResponsePrompt` + - `tools: array of object { input_schema, name, annotations, description }` - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + The tools available on the server. - - `id: string` + - `input_schema: unknown` - The unique identifier of the prompt template to use. + The JSON schema describing the tool's input. - - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` + - `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 name of the tool. - - `string` + - `annotations: optional unknown` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + Additional annotations about the tool. - A text input to the model. + - `description: optional string` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + The description of the tool. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `type: "mcp_list_tools"` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + The type of the item. Always `mcp_list_tools`. - A file input to the model. + - `"mcp_list_tools"` - - `version: optional string` + - `agent: optional object { agent_name }` - Optional version of the prompt template. + The agent that produced this item. -- `prompt_cache_key: optional string` + - `agent_name: string` - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + The canonical name of the agent that produced this item. -- `prompt_cache_options: optional object { mode, ttl }` + - `error: optional string` - Options for prompt caching. Supported for `gpt-5.6` and later models. By default, OpenAI automatically chooses one implicit cache breakpoint. You can add explicit breakpoints to content blocks with `prompt_cache_breakpoint`. Each request can write up to four breakpoints. For cache matching, OpenAI considers up to the latest 80 breakpoints in the conversation, without a content-block lookback limit. Set `mode` to `explicit` to disable the implicit breakpoint. The `ttl` defaults to `30m`, which is currently the only supported value. See the [prompt caching guide](https://platform.openai.com/docs/guides/prompt-caching) for current details. + Error message if the server could not list tools. - - `mode: optional "implicit" or "explicit"` + - `McpApprovalRequest object { id, arguments, name, 3 more }` - Controls whether OpenAI automatically creates an implicit cache breakpoint. Defaults to `implicit`. With `implicit`, OpenAI creates one implicit breakpoint and writes up to the latest three explicit breakpoints in the request. With `explicit`, OpenAI does not create an implicit breakpoint and writes up to the latest four explicit breakpoints. If there are no explicit breakpoints, the request does not use prompt caching. + A request for human approval of a tool invocation. - - `"implicit"` + - `id: string` - - `"explicit"` + The unique ID of the approval request. - - `ttl: optional "30m"` + - `arguments: 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. + A JSON string of arguments for the tool. - - `"30m"` + - `name: string` -- `prompt_cache_retention: optional "in_memory" or "24h"` + The name of the tool to run. - Deprecated. Use `prompt_cache_options.ttl` instead. + - `server_label: 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](https://platform.openai.com/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 label of the MCP server making the request. - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + - `type: "mcp_approval_request"` - - 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 item. Always `mcp_approval_request`. - - `"in_memory"` + - `"mcp_approval_request"` - - `"24h"` + - `agent: optional object { agent_name }` -- `reasoning: optional object { context, effort, generate_summary, 2 more }` + The agent that produced this item. - **gpt-5 and o-series models only** + - `agent_name: string` - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + The canonical name of the agent that produced this item. - - `context: optional "auto" or "current_turn" or "all_turns"` + - `McpApprovalResponse object { id, approval_request_id, approve, 3 more }` - Controls which reasoning items are rendered back to the model on later turns. - When returned on a response, this is the effective reasoning context mode - used for the response. + A response to an MCP approval request. - - `"auto"` + - `id: string` - - `"current_turn"` + The unique ID of the approval response - - `"all_turns"` + - `approval_request_id: string` - - `effort: optional "none" or "minimal" or "low" or 4 more` + The ID of the approval request being answered. - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + - `approve: boolean` - - `"none"` + Whether the request was approved. - - `"minimal"` + - `type: "mcp_approval_response"` - - `"low"` + The type of the item. Always `mcp_approval_response`. - - `"medium"` + - `"mcp_approval_response"` - - `"high"` + - `agent: optional object { agent_name }` - - `"xhigh"` + The agent that produced this item. - - `"max"` + - `agent_name: string` - - `generate_summary: optional "auto" or "concise" or "detailed"` + The canonical name of the agent that produced this item. - **Deprecated:** use `summary` instead. + - `reason: 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`. + Optional reason for the decision. - - `"auto"` + - `CustomToolCall object { call_id, input, name, 5 more }` - - `"concise"` + A call to a custom tool created by the model. - - `"detailed"` + - `call_id: string` - - `mode: optional string or "standard" or "pro"` + An identifier used to map this custom tool call to a tool call output. - Controls the reasoning execution mode for the request. + - `input: string` - When returned on a response, this is the effective execution mode. + The input for the custom tool call generated by the model. - - `string` + - `name: string` - - `"standard" or "pro"` + The name of the custom tool being called. - Controls the reasoning execution mode for the request. + - `type: "custom_tool_call"` - When returned on a response, this is the effective execution mode. + The type of the custom tool call. Always `custom_tool_call`. - - `"standard"` + - `"custom_tool_call"` - - `"pro"` + - `id: optional string` - - `summary: optional "auto" or "concise" or "detailed"` + The unique ID of the custom tool call in the OpenAI platform. - 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 }` - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + The agent that produced this item. - - `"auto"` + - `agent_name: string` - - `"concise"` + The canonical name of the agent that produced this item. - - `"detailed"` + - `caller: optional object { type } or object { caller_id, type }` -- `safety_identifier: optional string` + The execution context that produced this tool call. - 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](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `Direct object { type }` -- `service_tier: optional "auto" or "default" or "flex" or 2 more` + - `type: "direct"` - Specifies the processing type used for serving the request. + - `"direct"` - - 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](https://platform.openai.com/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'. + - `Program object { caller_id, type }` - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + - `caller_id: string` - - `"auto"` + The call ID of the program item that produced this tool call. - - `"default"` + - `type: "program"` - - `"flex"` + - `"program"` - - `"scale"` + - `namespace: optional string` - - `"priority"` + The namespace of the custom tool being called. -- `store: optional boolean` + - `CustomToolCallOutput object { id, call_id, output, 5 more }` - Whether to store the generated model response for later retrieval via - API. + - `id: string` -- `stream: optional boolean` + The unique ID of the custom tool call output item. - 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](https://platform.openai.com/docs/api-reference/responses-streaming) - for more information. + - `call_id: string` -- `stream_options: optional object { include_obfuscation }` + The call ID, used to map this custom tool call output to a custom tool call. - Options for streaming responses. Only set this when you set `stream: true`. + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `include_obfuscation: optional boolean` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - 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. + - `StringOutput = string` -- `temperature: optional number` + A string of the output of the custom 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. + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` -- `text: optional BetaResponseTextConfig` + Text, image, or file output of the custom tool call. - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + A text input to the model. - - `format: optional BetaResponseFormatTextConfig` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - An object specifying the format that the model must output. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - Configuring `{ "type": "json_schema" }` enables Structured Outputs, - which ensures the model will match your supplied JSON schema. Learn more in the - [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - The default format is `{ "type": "text" }` with no additional options. + A file input to the model. - **Not recommended for gpt-4o and newer models:** + - `status: "in_progress" or "completed" or "incomplete"` - 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 status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `Text object { type }` + - `"in_progress"` - Default response format. Used to generate text responses. + - `"completed"` - - `type: "text"` + - `"incomplete"` - The type of response format being defined. Always `text`. + - `type: "custom_tool_call_output"` - - `"text"` + The type of the custom tool call output. Always `custom_tool_call_output`. - - `BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` + - `"custom_tool_call_output"` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `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` - - `schema: map[unknown]` + The canonical name of the agent that produced this item. - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `caller: optional object { type } or object { caller_id, type }` - - `type: "json_schema"` + The execution context that produced this tool call. - The type of response format being defined. Always `json_schema`. + - `Direct object { type }` - - `"json_schema"` + - `type: "direct"` - - `description: optional string` + The caller type. Always `direct`. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `"direct"` - - `strict: optional boolean` + - `Program object { caller_id, type }` - 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](https://platform.openai.com/docs/guides/structured-outputs). + - `caller_id: string` - - `JSONObject 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"` + The caller type. Always `program`. - The type of response format being defined. Always `json_object`. + - `"program"` - - `"json_object"` + - `created_by: optional string` - - `verbosity: optional "low" or "medium" or "high"` + The identifier of the actor that created the item. - 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`. + - `parallel_tool_calls: boolean` - - `"low"` + Whether to allow the model to run tool calls in parallel. - - `"medium"` + - `temperature: number` - - `"high"` + 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: optional BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` + - `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 @@ -26682,12 +27527,12 @@ Create a model response - `BetaToolChoiceTypes object { type }` Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + [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](https://platform.openai.com/docs/guides/tools). + [built-in tools](/docs/guides/tools). Allowed values are: @@ -26789,7 +27634,7 @@ Create a model response - `"shell"` -- `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` + - `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. @@ -26797,16 +27642,16 @@ Create a model response 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](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + 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](https://platform.openai.com/docs/guides/tools-connectors-mcp). + [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](https://platform.openai.com/docs/guides/function-calling). You can also use + [function calling](/docs/guides/function-calling). You can also use custom tools to call your own code. - `Function object { name, parameters, strict, 5 more }` @@ -27070,7 +27915,7 @@ Create a model response - `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](https://platform.openai.com/docs/guides/tools-web-search). + [web search tool](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -27130,7 +27975,7 @@ Create a model response - `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](https://platform.openai.com/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -27182,7 +28027,7 @@ Create a model response 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -27374,19 +28219,8 @@ Create a model response - `background: optional "transparent" or "opaque" or "auto"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. - - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. - - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - `"transparent"` @@ -27415,13 +28249,13 @@ Create a model response Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `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-2" or 3 more` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` The image generation model to use. Default: `gpt-image-1`. @@ -27429,14 +28263,8 @@ Create a model response - `"gpt-image-1-mini"` - - `"gpt-image-2"` - - - `"gpt-image-2-2026-04-21"` - - `"gpt-image-1.5"` - - `"chatgpt-image-latest"` - - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -27533,7 +28361,7 @@ Create a model response - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -27647,7 +28475,7 @@ Create a model response - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -27815,14 +28643,7 @@ Create a model response - `"programmatic"` -- `top_logprobs: optional number` - - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. - -- `top_p: optional number` + - `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 @@ -27831,7 +28652,467 @@ Create a model response We generally recommend altering this or `temperature` but not both. -- `truncation: optional "auto" or "disabled"` + - `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. + 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`. + + - `"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. @@ -27845,15 +29126,365 @@ Create a model response - `"disabled"` -- `user: optional string` + - `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](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](/docs/guides/safety-best-practices#safety-identifiers). + +### Example + +```http +curl https://api.openai.com/v1/responses/$RESPONSE_ID \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` + +#### Response + +```json +{ + "id": "id", + "created_at": 0, + "error": { + "code": "server_error", + "message": "message" + }, + "incomplete_details": { + "reason": "max_output_tokens" + }, + "instructions": "string", + "metadata": { + "foo": "string" + }, + "model": "gpt-5.1", + "object": "response", + "output": [ + { + "id": "id", + "content": [ + { + "annotations": [ + { + "file_id": "file_id", + "filename": "filename", + "index": 0, + "type": "file_citation" + } + ], + "logprobs": [ + { + "token": "token", + "bytes": [ + 0 + ], + "logprob": 0, + "top_logprobs": [ + { + "token": "token", + "bytes": [ + 0 + ], + "logprob": 0 + } + ] + } + ], + "text": "text", + "type": "output_text" + } + ], + "role": "assistant", + "status": "in_progress", + "type": "message", + "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" +} +``` + +### Example + +```http +curl https://api.openai.com/v1/responses/resp_123 \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` + +#### Response + +```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 + }, + "output_tokens": 18, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 50 + }, + "user": null, + "metadata": {} +} +``` + +## Delete a model response + +**delete** `/responses/{response_id}?beta=true` + +Deletes a model response with the given ID. + +### Path Parameters + +- `response_id: string` + +### Header Parameters + +- `"openai-beta": optional array of "responses_multi_agent=v1"` + + - `"responses_multi_agent=v1"` + +### Example + +```http +curl https://api.openai.com/v1/responses/$RESPONSE_ID \ + -X DELETE \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` + +### Example + +```http +curl -X DELETE https://api.openai.com/v1/responses/resp_123 \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` + +#### Response + +```json +{ + "id": "resp_6786a1bec27481909a17d673315b29f6", + "object": "response", + "deleted": true +} +``` + +## Cancel a response + +**post** `/responses/{response_id}/cancel?beta=true` + +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). + +### Path Parameters + +- `response_id: string` + +### Header Parameters + +- `"openai-beta": optional array of "responses_multi_agent=v1"` + + - `"responses_multi_agent=v1"` ### Returns -- `BetaResponse object { id, created_at, error, 31 more }` +- `BetaResponse object { id, created_at, error, 32 more }` - `id: string` @@ -27991,7 +29622,7 @@ Create a model response - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + An image input to the model. Learn about [image inputs](/docs/guides/vision). - `detail: "low" or "high" or "auto" or "original"` @@ -28162,7 +29793,7 @@ Create a model response The content of the output message. - - `BetaResponseOutputText object { annotations, text, type, logprobs }` + - `BetaResponseOutputText object { annotations, logprobs, text, type }` A text output from the model. @@ -28266,17 +29897,7 @@ Create a model response - `"file_path"` - - `text: string` - - The text output from the model. - - - `type: "output_text"` - - The type of the output text. Always `output_text`. - - - `"output_text"` - - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - `token: string` @@ -28292,6 +29913,16 @@ Create a model response - `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. @@ -28350,7 +29981,7 @@ Create a model response - `FileSearchCall object { id, queries, status, 3 more }` The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + [file search guide](/docs/guides/tools-file-search) for more information. - `id: string` @@ -28426,7 +30057,7 @@ Create a model response - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + [computer use guide](/docs/guides/tools-computer-use) for more information. - `id: string` @@ -28787,7 +30418,7 @@ Create a model response - `WebSearchCall object { id, action, status, 2 more }` The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + [web search guide](/docs/guides/tools-web-search) for more information. - `id: string` @@ -28891,7 +30522,7 @@ Create a model response - `FunctionCall object { arguments, call_id, name, 6 more }` A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + [function calling guide](/docs/guides/function-calling) for more information. - `arguments: string` @@ -28966,7 +30597,7 @@ Create a model response The unique ID of the function tool call generated by the model. - - `output: string or BetaResponseFunctionCallOutputItemList` + - `output: string or array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` Text, image, or file output of the function tool call. @@ -28974,7 +30605,7 @@ Create a model response A JSON string of the output of the function tool call. - - `BetaResponseFunctionCallOutputItemList = array of BetaResponseFunctionCallOutputItem` + - `array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` An array of content outputs (text, image, file) for the function tool call. @@ -29004,7 +30635,7 @@ Create a model response - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + An image input to the model. Learn about [image inputs](/docs/guides/vision) - `type: "input_image"` @@ -29158,7 +30789,7 @@ Create a model response - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + An image input to the model. Learn about [image inputs](/docs/guides/vision) - `EncryptedContent object { encrypted_content, type }` @@ -29683,7 +31314,7 @@ Create a model response - `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](https://platform.openai.com/docs/guides/tools-web-search). + [web search tool](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -29743,7 +31374,7 @@ Create a model response - `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](https://platform.openai.com/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -29795,7 +31426,7 @@ Create a model response 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -30019,19 +31650,8 @@ Create a model response - `background: optional "transparent" or "opaque" or "auto"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. - - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. - - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - `"transparent"` @@ -30060,13 +31680,13 @@ Create a model response Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `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-2" or 3 more` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` The image generation model to use. Default: `gpt-image-1`. @@ -30074,14 +31694,8 @@ Create a model response - `"gpt-image-1-mini"` - - `"gpt-image-2"` - - - `"gpt-image-2-2026-04-21"` - - `"gpt-image-1.5"` - - `"chatgpt-image-latest"` - - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -30296,7 +31910,7 @@ Create a model response - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -30410,7 +32024,7 @@ Create a model response - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -30891,7 +32505,7 @@ Create a model response - `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](https://platform.openai.com/docs/guides/tools-web-search). + [web search tool](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -30951,7 +32565,7 @@ Create a model response - `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](https://platform.openai.com/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -31003,7 +32617,7 @@ Create a model response 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -31195,19 +32809,8 @@ Create a model response - `background: optional "transparent" or "opaque" or "auto"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. - - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. - - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - `"transparent"` @@ -31236,13 +32839,13 @@ Create a model response Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `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-2" or 3 more` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` The image generation model to use. Default: `gpt-image-1`. @@ -31250,14 +32853,8 @@ Create a model response - `"gpt-image-1-mini"` - - `"gpt-image-2"` - - - `"gpt-image-2-2026-04-21"` - - `"gpt-image-1.5"` - - `"chatgpt-image-latest"` - - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -31354,7 +32951,7 @@ Create a model response - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -31468,7 +33065,7 @@ Create a model response - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -31659,7 +33256,7 @@ Create 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](https://platform.openai.com/docs/guides/conversation-state). + [managing context](/docs/guides/conversation-state). - `id: string` @@ -31725,7 +33322,7 @@ Create a model response - `Compaction object { encrypted_content, type, id, agent }` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). - `encrypted_content: string` @@ -32534,7 +34131,7 @@ Create a model response - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + An image input to the model. Learn about [image inputs](/docs/guides/vision). - `BetaResponseInputFile object { type, detail, file_data, 4 more }` @@ -32761,14 +34358,14 @@ Create a model response 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](https://platform.openai.com/docs/models) + 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](https://platform.openai.com/docs/models) + characteristics, and price points. Refer to the [model guide](/docs/models) to browse and compare available models. - `"gpt-5.6-sol"` @@ -32987,7 +34584,7 @@ Create a model response - `FileSearchCall object { id, queries, status, 3 more }` The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + [file search guide](/docs/guides/tools-file-search) for more information. - `id: string` @@ -33063,7 +34660,7 @@ Create a model response - `FunctionCall object { arguments, call_id, name, 6 more }` A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + [function calling guide](/docs/guides/function-calling) for more information. - `arguments: string` @@ -33159,7 +34756,7 @@ Create a model response - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + An image input to the model. Learn about [image inputs](/docs/guides/vision). - `BetaResponseInputFile object { type, detail, file_data, 4 more }` @@ -33236,7 +34833,7 @@ Create a model response A text input to the model. - - `BetaResponseOutputText object { annotations, text, type, logprobs }` + - `BetaResponseOutputText object { annotations, logprobs, text, type }` A text output from the model. @@ -33284,7 +34881,7 @@ Create a model response - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + An image input to the model. Learn about [image inputs](/docs/guides/vision). - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` @@ -33440,6 +35037,8 @@ Create a model response The annotations of the text output. + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + - `text: string` The text output from the model. @@ -33448,8 +35047,6 @@ Create a model response The type of the output text. Always `output_text`. - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` - - `type: "multi_agent_call_output"` The type of the multi-agent result. Always `multi_agent_call_output`. @@ -33467,7 +35064,7 @@ Create a model response - `WebSearchCall object { id, action, status, 2 more }` The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + [web search guide](/docs/guides/tools-web-search) for more information. - `id: string` @@ -33571,7 +35168,7 @@ Create a model response - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + [computer use guide](/docs/guides/tools-computer-use) for more information. - `id: string` @@ -33698,7 +35295,7 @@ Create 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](https://platform.openai.com/docs/guides/conversation-state). + [managing context](/docs/guides/conversation-state). - `id: string` @@ -34173,7 +35770,7 @@ Create a model response - `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](https://platform.openai.com/docs/guides/tools-web-search). + [web search tool](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -34233,7 +35830,7 @@ Create a model response - `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](https://platform.openai.com/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -34285,7 +35882,7 @@ Create a model response 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -34477,19 +36074,8 @@ Create a model response - `background: optional "transparent" or "opaque" or "auto"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. - - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. - - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - `"transparent"` @@ -34518,13 +36104,13 @@ Create a model response Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `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-2" or 3 more` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` The image generation model to use. Default: `gpt-image-1`. @@ -34532,14 +36118,8 @@ Create a model response - `"gpt-image-1-mini"` - - `"gpt-image-2"` - - - `"gpt-image-2-2026-04-21"` - - `"gpt-image-1.5"` - - `"chatgpt-image-latest"` - - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -34636,7 +36216,7 @@ Create a model response - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -34750,7 +36330,7 @@ Create a model response - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -35227,7 +36807,7 @@ Create a model response - `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](https://platform.openai.com/docs/guides/tools-web-search). + [web search tool](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -35287,7 +36867,7 @@ Create a model response - `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](https://platform.openai.com/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -35339,7 +36919,7 @@ Create a model response 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -35531,19 +37111,8 @@ Create a model response - `background: optional "transparent" or "opaque" or "auto"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. - - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. - - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - `"transparent"` @@ -35572,13 +37141,13 @@ Create a model response Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `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-2" or 3 more` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` The image generation model to use. Default: `gpt-image-1`. @@ -35586,14 +37155,8 @@ Create a model response - `"gpt-image-1-mini"` - - `"gpt-image-2"` - - - `"gpt-image-2-2026-04-21"` - - `"gpt-image-1.5"` - - `"chatgpt-image-latest"` - - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -35690,7 +37253,7 @@ Create a model response - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -35804,7 +37367,7 @@ Create a model response - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -35988,7 +37551,7 @@ Create a model response - `Compaction object { id, encrypted_content, type, 2 more }` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). - `id: string` @@ -36881,7 +38444,7 @@ Create a model response - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + An image input to the model. Learn about [image inputs](/docs/guides/vision). - `BetaResponseInputFile object { type, detail, file_data, 4 more }` @@ -37012,12 +38575,12 @@ Create a model response - `BetaToolChoiceTypes object { type }` Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + [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](https://platform.openai.com/docs/guides/tools). + [built-in tools](/docs/guides/tools). Allowed values are: @@ -37127,16 +38690,16 @@ Create a model response 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](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + 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](https://platform.openai.com/docs/guides/tools-connectors-mcp). + [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](https://platform.openai.com/docs/guides/function-calling). You can also use + [function calling](/docs/guides/function-calling). You can also use custom tools to call your own code. - `Function object { name, parameters, strict, 5 more }` @@ -37400,7 +38963,7 @@ Create a model response - `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](https://platform.openai.com/docs/guides/tools-web-search). + [web search tool](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -37460,7 +39023,7 @@ Create a model response - `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](https://platform.openai.com/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -37512,7 +39075,7 @@ Create a model response 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -37704,19 +39267,8 @@ Create a model response - `background: optional "transparent" or "opaque" or "auto"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. - - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. - - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - `"transparent"` @@ -37745,13 +39297,13 @@ Create a model response Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `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-2" or 3 more` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` The image generation model to use. Default: `gpt-image-1`. @@ -37759,14 +39311,8 @@ Create a model response - `"gpt-image-1-mini"` - - `"gpt-image-2"` - - - `"gpt-image-2-2026-04-21"` - - `"gpt-image-1.5"` - - `"chatgpt-image-latest"` - - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -37863,7 +39409,7 @@ Create a model response - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -37977,7 +39523,7 @@ Create a model response - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -38157,7 +39703,7 @@ Create a model response - `background: optional boolean` Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + [Learn more](/docs/guides/background). - `completed_at: optional number` @@ -38174,7 +39720,7 @@ Create a model response - `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](https://platform.openai.com/docs/guides/reasoning). + 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` @@ -38296,16 +39842,22 @@ Create a model response - `"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](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + [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](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + [Learn more](/docs/guides/text?api-mode=responses#reusable-prompts). - `id: string` @@ -38325,7 +39877,7 @@ Create a model response - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + An image input to the model. Learn about [image inputs](/docs/guides/vision). - `BetaResponseInputFile object { type, detail, file_data, 4 more }` @@ -38337,7 +39889,7 @@ Create a model response - `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](https://platform.openai.com/docs/guides/prompt-caching). + 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 }` @@ -38361,7 +39913,7 @@ Create a model response 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](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + 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. @@ -38468,7 +40020,7 @@ Create a model response - `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](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + 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` @@ -38476,7 +40028,7 @@ Create a model response - 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](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - 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. @@ -38513,8 +40065,8 @@ Create a model response Configuration options for a text response from the model. Can be plain text or structured JSON data. Learn more: - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - [Text inputs and outputs](/docs/guides/text) + - [Structured Outputs](/docs/guides/structured-outputs) - `format: optional BetaResponseFormatTextConfig` @@ -38522,7 +40074,7 @@ Create a model response Configuring `{ "type": "json_schema" }` enables Structured Outputs, which ensures the model will match your supplied JSON schema. Learn more in the - [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + [Structured Outputs guide](/docs/guides/structured-outputs). The default format is `{ "type": "text" }` with no additional options. @@ -38545,7 +40097,7 @@ Create a model response - `BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - `name: string` @@ -38574,7 +40126,7 @@ Create a model response 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](https://platform.openai.com/docs/guides/structured-outputs). + guide](/docs/guides/structured-outputs). - `JSONObject object { type }` @@ -38642,7 +40194,7 @@ Create a model response - `cached_tokens: number` The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + [More on prompt caching](/docs/guides/prompt-caching). - `output_tokens: number` @@ -38664,23 +40216,14 @@ Create a model response 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](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](/docs/guides/safety-best-practices#safety-identifiers). ### Example ```http -curl https://api.openai.com/v1/responses \ - -H 'Content-Type: application/json' \ - -H 'OpenAI-Beta: assistants=v2' \ - -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 @@ -38715,8 +40258,6 @@ curl https://api.openai.com/v1/responses \ "type": "file_citation" } ], - "text": "text", - "type": "output_text", "logprobs": [ { "token": "token", @@ -38734,7 +40275,9 @@ curl https://api.openai.com/v1/responses \ } ] } - ] + ], + "text": "text", + "type": "output_text" } ], "role": "assistant", @@ -38858,127 +40401,39 @@ curl https://api.openai.com/v1/responses \ } ``` -### Text input - -```http -curl https://api.openai.com/v1/responses \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -d '{ - "model": "gpt-5.4", - "input": "Tell me a three sentence bedtime story about a unicorn." - }' -``` - -#### Response - -```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 - }, - "output_tokens": 87, - "output_tokens_details": { - "reasoning_tokens": 0 - }, - "total_tokens": 123 - }, - "user": null, - "metadata": {} -} -``` - -### Image 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": [ - { - "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" - } - ] - } - ] - }' + -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { - "id": "resp_67ccd3a9da748190baa7f1570fe91ac604becb25c45c1d41", + "id": "resp_67cb71b351908190a308f3859487620d06981a8637e6bc44", "object": "response", - "created_at": 1741476777, - "status": "completed", - "completed_at": 1741476778, + "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_67ccd3acc8d48190a77525dc6de64b4104becb25c45c1d41", - "status": "completed", + "id": "msg_67cb71b3c2b0819084d481baaaf148f206981a8637e6bc44", + "status": "in_progress", "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.", + "text": "Silent circuits hum, \nThoughts emerge in data streams— \nDigital dawn breaks.", "annotations": [] } ] @@ -39001,770 +40456,239 @@ curl https://api.openai.com/v1/responses \ "tools": [], "top_p": 1.0, "truncation": "disabled", - "usage": { - "input_tokens": 328, - "input_tokens_details": { - "cached_tokens": 0 - }, - "output_tokens": 52, - "output_tokens_details": { - "reasoning_tokens": 0 - }, - "total_tokens": 380 - }, + "usage": null, "user": null, "metadata": {} } ``` -### File 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 file?"}, - { - "type": "input_file", - "file_url": "https://www.berkshirehathaway.com/letters/2024ltr.pdf", - "detail": "auto" - } - ] - } - ] - }' -``` +**post** `/responses/compact?beta=true` -#### Response +Compact a conversation. Returns a compacted response object. -```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 - }, - "output_tokens": 398, - "output_tokens_details": { - "reasoning_tokens": 0 - }, - "total_tokens": 8836 - }, - "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). -### Web search +### 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", - "tools": [{ "type": "web_search_preview" }], - "input": "What was a positive news story from today?" - }' -``` +- `"openai-beta": optional array of "responses_multi_agent=v1"` -#### Response + - `"responses_multi_agent=v1"` -```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 - }, - "output_tokens": 356, - "output_tokens_details": { - "reasoning_tokens": 0 - }, - "total_tokens": 684 - }, - "user": null, - "metadata": {} -} -``` +### Body Parameters -### File 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": "file_search", - "vector_store_ids": ["vs_1234567890"], - "max_num_results": 20 - }], - "input": "What are the attributes of an ancient brown dragon?" - }' -``` + 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_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 - }, - "output_tokens": 348, - "output_tokens_details": { - "reasoning_tokens": 0 - }, - "total_tokens": 18655 - }, - "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. -### Streaming + - `"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", - "instructions": "You are a helpful assistant.", - "input": "Hello!", - "stream": true - }' -``` + - `"gpt-5.6-terra"` -#### Response + - `"gpt-5.6-luna"` -```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"` -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.4-mini"` -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.4-nano"` -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.4-mini-2026-03-17"` -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.4-nano-2026-03-17"` -... + - `"gpt-5.3-chat-latest"` -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"` -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.2-2025-12-11"` -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.2-chat-latest"` -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.2-pro"` -### Functions + - `"gpt-5.2-pro-2025-12-11"` -```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"` -#### Response + - `"gpt-5.1-2025-11-13"` -```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.1-codex"` -### Reasoning + - `"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": "o3-mini", - "input": "How much wood would a woodchuck chuck?", - "reasoning": { - "effort": "high" - } - }' -``` + - `"gpt-5.1-chat-latest"` -#### Response + - `"gpt-5"` -```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 - }, - "output_tokens": 1035, - "output_tokens_details": { - "reasoning_tokens": 832 - }, - "total_tokens": 1116 - }, - "user": null, - "metadata": {} -} -``` + - `"gpt-5-mini"` -## Get a model response + - `"gpt-5-nano"` -**get** `/responses/{response_id}?beta=true` + - `"gpt-5-2025-08-07"` -Get a model response + - `"gpt-5-mini-2025-08-07"` -### Path Parameters + - `"gpt-5-nano-2025-08-07"` -- `response_id: string` + - `"gpt-5-chat-latest"` -### Query Parameters + - `"gpt-4.1"` -- `include: optional array of BetaResponseIncludable` + - `"gpt-4.1-mini"` - Additional fields to include in the response. See the `include` - parameter for Response creation above for more information. + - `"gpt-4.1-nano"` - - `"file_search_call.results"` + - `"gpt-4.1-2025-04-14"` - - `"web_search_call.results"` + - `"gpt-4.1-mini-2025-04-14"` - - `"web_search_call.action.sources"` + - `"gpt-4.1-nano-2025-04-14"` - - `"message.input_image.image_url"` + - `"o4-mini"` - - `"computer_call_output.output.image_url"` + - `"o4-mini-2025-04-16"` - - `"code_interpreter_call.outputs"` + - `"o3"` - - `"reasoning.encrypted_content"` + - `"o3-2025-04-16"` - - `"message.output_text.logprobs"` + - `"o3-mini"` -- `include_obfuscation: optional boolean` + - `"o3-mini-2025-01-31"` - 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"` -- `starting_after: optional number` + - `"o1-2024-12-17"` - The sequence number of the event after which to start streaming. + - `"o1-preview"` -- `stream: optional false` + - `"o1-preview-2024-09-12"` - 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](https://platform.openai.com/docs/api-reference/responses-streaming) - for more information. + - `"o1-mini"` - - `false` + - `"o1-mini-2024-09-12"` -### Header Parameters + - `"gpt-4o"` -- `"openai-beta": optional array of "responses_multi_agent=v1"` + - `"gpt-4o-2024-11-20"` - - `"responses_multi_agent=v1"` + - `"gpt-4o-2024-08-06"` -### Returns + - `"gpt-4o-2024-05-13"` -- `BetaResponse object { id, created_at, error, 31 more }` + - `"gpt-4o-audio-preview"` - - `id: string` + - `"gpt-4o-audio-preview-2024-10-01"` - Unique identifier for this Response. + - `"gpt-4o-audio-preview-2024-12-17"` - - `created_at: number` + - `"gpt-4o-audio-preview-2025-06-03"` - Unix timestamp (in seconds) of when this Response was created. + - `"gpt-4o-mini-audio-preview"` - - `error: BetaResponseError` + - `"gpt-4o-mini-audio-preview-2024-12-17"` - An error object returned when the model fails to generate a Response. + - `"gpt-4o-search-preview"` - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 16 more` + - `"gpt-4o-mini-search-preview"` - The error code for the response. + - `"gpt-4o-search-preview-2025-03-11"` - - `"server_error"` + - `"gpt-4o-mini-search-preview-2025-03-11"` - - `"rate_limit_exceeded"` + - `"chatgpt-4o-latest"` - - `"invalid_prompt"` + - `"codex-mini-latest"` - - `"bio_policy"` + - `"gpt-4o-mini"` - - `"vector_store_timeout"` + - `"gpt-4o-mini-2024-07-18"` - - `"invalid_image"` + - `"gpt-4-turbo"` - - `"invalid_image_format"` + - `"gpt-4-turbo-2024-04-09"` - - `"invalid_base64_image"` + - `"gpt-4-0125-preview"` - - `"invalid_image_url"` + - `"gpt-4-turbo-preview"` - - `"image_too_large"` + - `"gpt-4-1106-preview"` - - `"image_too_small"` + - `"gpt-4-vision-preview"` - - `"image_parse_error"` + - `"gpt-4"` - - `"image_content_policy_violation"` + - `"gpt-4-0314"` - - `"invalid_image_mode"` + - `"gpt-4-0613"` - - `"image_file_too_large"` + - `"gpt-4-32k"` - - `"unsupported_image_media_type"` + - `"gpt-4-32k-0314"` - - `"empty_image_file"` + - `"gpt-4-32k-0613"` - - `"failed_to_download_image"` + - `"gpt-3.5-turbo"` - - `"image_file_not_found"` + - `"gpt-3.5-turbo-16k"` - - `message: string` + - `"gpt-3.5-turbo-0301"` - A human-readable description of the error. + - `"gpt-3.5-turbo-0613"` - - `incomplete_details: object { reason }` + - `"gpt-3.5-turbo-1106"` - Details about why the response is incomplete. + - `"gpt-3.5-turbo-0125"` - - `reason: optional "max_output_tokens" or "content_filter"` + - `"gpt-3.5-turbo-16k-0613"` - The reason why the response is incomplete. + - `"o1-pro"` - - `"max_output_tokens"` + - `"o1-pro-2025-03-19"` - - `"content_filter"` + - `"o3-pro"` - - `instructions: string or array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + - `"o3-pro-2025-06-10"` - A system (or developer) message inserted into the model's context. + - `"o3-deep-research"` - 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. + - `"o3-deep-research-2025-06-26"` + + - `"o4-mini-deep-research"` + + - `"o4-mini-deep-research-2025-06-26"` + + - `"computer-use-preview"` + + - `"computer-use-preview-2025-03-11"` + + - `"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 }` @@ -39814,7 +40738,7 @@ Get a model response - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + An image input to the model. Learn about [image inputs](/docs/guides/vision). - `detail: "low" or "high" or "auto" or "original"` @@ -39985,7 +40909,7 @@ Get a model response The content of the output message. - - `BetaResponseOutputText object { annotations, text, type, logprobs }` + - `BetaResponseOutputText object { annotations, logprobs, text, type }` A text output from the model. @@ -40089,17 +41013,7 @@ Get a model response - `"file_path"` - - `text: string` - - The text output from the model. - - - `type: "output_text"` - - The type of the output text. Always `output_text`. - - - `"output_text"` - - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - `token: string` @@ -40115,6 +41029,16 @@ Get a model response - `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. @@ -40173,7 +41097,7 @@ Get a model response - `FileSearchCall object { id, queries, status, 3 more }` The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + [file search guide](/docs/guides/tools-file-search) for more information. - `id: string` @@ -40249,7 +41173,7 @@ Get a model response - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + [computer use guide](/docs/guides/tools-computer-use) for more information. - `id: string` @@ -40610,7 +41534,7 @@ Get a model response - `WebSearchCall object { id, action, status, 2 more }` The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + [web search guide](/docs/guides/tools-web-search) for more information. - `id: string` @@ -40714,7 +41638,7 @@ Get a model response - `FunctionCall object { arguments, call_id, name, 6 more }` A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + [function calling guide](/docs/guides/function-calling) for more information. - `arguments: string` @@ -40789,7 +41713,7 @@ Get a model response The unique ID of the function tool call generated by the model. - - `output: string or BetaResponseFunctionCallOutputItemList` + - `output: string or array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` Text, image, or file output of the function tool call. @@ -40797,7 +41721,7 @@ Get a model response A JSON string of the output of the function tool call. - - `BetaResponseFunctionCallOutputItemList = array of BetaResponseFunctionCallOutputItem` + - `array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` An array of content outputs (text, image, file) for the function tool call. @@ -40827,7 +41751,7 @@ Get a model response - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + An image input to the model. Learn about [image inputs](/docs/guides/vision) - `type: "input_image"` @@ -40981,7 +41905,7 @@ Get a model response - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + An image input to the model. Learn about [image inputs](/docs/guides/vision) - `EncryptedContent object { encrypted_content, type }` @@ -41506,7 +42430,7 @@ Get a model response - `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](https://platform.openai.com/docs/guides/tools-web-search). + [web search tool](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -41566,7 +42490,7 @@ Get a model response - `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](https://platform.openai.com/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -41618,7 +42542,7 @@ Get a model response 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -41842,19 +42766,8 @@ Get a model response - `background: optional "transparent" or "opaque" or "auto"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. - - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. - - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - `"transparent"` @@ -41883,13 +42796,13 @@ Get a model response Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `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-2" or 3 more` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` The image generation model to use. Default: `gpt-image-1`. @@ -41897,14 +42810,8 @@ Get a model response - `"gpt-image-1-mini"` - - `"gpt-image-2"` - - - `"gpt-image-2-2026-04-21"` - - `"gpt-image-1.5"` - - `"chatgpt-image-latest"` - - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -42119,7 +43026,7 @@ Get a model response - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -42233,7 +43140,7 @@ Get a model response - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -42714,7 +43621,7 @@ Get a model response - `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](https://platform.openai.com/docs/guides/tools-web-search). + [web search tool](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -42774,7 +43681,7 @@ Get a model response - `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](https://platform.openai.com/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -42826,7 +43733,7 @@ Get a model response 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -43018,19 +43925,8 @@ Get a model response - `background: optional "transparent" or "opaque" or "auto"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. - - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. - - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - `"transparent"` @@ -43059,13 +43955,13 @@ Get a model response Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `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-2" or 3 more` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` The image generation model to use. Default: `gpt-image-1`. @@ -43073,14 +43969,8 @@ Get a model response - `"gpt-image-1-mini"` - - `"gpt-image-2"` - - - `"gpt-image-2-2026-04-21"` - - `"gpt-image-1.5"` - - `"chatgpt-image-latest"` - - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -43177,7 +44067,7 @@ Get a model response - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -43291,7 +44181,7 @@ Get a model response - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -43482,7 +44372,7 @@ Get 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](https://platform.openai.com/docs/guides/conversation-state). + [managing context](/docs/guides/conversation-state). - `id: string` @@ -43548,7 +44438,7 @@ Get a model response - `Compaction object { encrypted_content, type, id, agent }` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). - `encrypted_content: string` @@ -44357,7 +45247,7 @@ Get a model response - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + An image input to the model. Learn about [image inputs](/docs/guides/vision). - `BetaResponseInputFile object { type, detail, file_data, 4 more }` @@ -44571,497 +45461,244 @@ Get a model response 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](https://platform.openai.com/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](https://platform.openai.com/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](https://platform.openai.com/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](https://platform.openai.com/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](https://platform.openai.com/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, text, type, logprobs }` + The type of the output text. Always `output_text`. - A text output from the model. + - `"output_text"` - `Text object { text, type }` @@ -45105,17 +45742,23 @@ Get a model response 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](https://platform.openai.com/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"` @@ -45125,19 +45768,19 @@ Get a model response - `"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 }` @@ -45149,135 +45792,141 @@ Get a model response - `"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"` - - `text: string` + - `"discriminator"` - The text output from the model. + - `"developer"` - - `type: "output_text"` + - `"tool"` - The type of the output text. Always `output_text`. + - `status: "in_progress" or "completed" or "incomplete"` - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + 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 }` @@ -45287,101 +45936,37 @@ Get a model response 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](https://platform.openai.com/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 }` @@ -45391,60 +45976,33 @@ Get a model response 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](https://platform.openai.com/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 }` @@ -45454,55 +46012,32 @@ Get a model response 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 }` @@ -45512,138 +46047,134 @@ Get a model response 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](https://platform.openai.com/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 - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `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 }` @@ -45996,7 +46527,7 @@ Get a model response - `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](https://platform.openai.com/docs/guides/tools-web-search). + [web search tool](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -46056,7 +46587,7 @@ Get a model response - `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](https://platform.openai.com/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -46108,7 +46639,7 @@ Get a model response 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -46254,8 +46785,40 @@ Get a model response - `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`. @@ -46300,19 +46863,8 @@ Get a model response - `background: optional "transparent" or "opaque" or "auto"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. - - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. - - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - `"transparent"` @@ -46341,13 +46893,13 @@ Get a model response Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `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-2" or 3 more` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` The image generation model to use. Default: `gpt-image-1`. @@ -46355,14 +46907,8 @@ Get a model response - `"gpt-image-1-mini"` - - `"gpt-image-2"` - - - `"gpt-image-2-2026-04-21"` - - `"gpt-image-1.5"` - - `"chatgpt-image-latest"` - - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -46453,13 +46999,131 @@ Get a model response - `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](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -46573,7 +47237,7 @@ Get a model response - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -47050,7 +47714,7 @@ Get a model response - `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](https://platform.openai.com/docs/guides/tools-web-search). + [web search tool](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -47110,7 +47774,7 @@ Get a model response - `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](https://platform.openai.com/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -47162,7 +47826,7 @@ Get a model response 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -47354,19 +48018,8 @@ Get a model response - `background: optional "transparent" or "opaque" or "auto"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. - - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. - - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - `"transparent"` @@ -47395,13 +48048,13 @@ Get a model response Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `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-2" or 3 more` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` The image generation model to use. Default: `gpt-image-1`. @@ -47409,14 +48062,8 @@ Get a model response - `"gpt-image-1-mini"` - - `"gpt-image-2"` - - - `"gpt-image-2-2026-04-21"` - - `"gpt-image-1.5"` - - `"chatgpt-image-latest"` - - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -47513,7 +48160,7 @@ Get a model response - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -47627,7 +48274,7 @@ Get a model response - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -47809,23 +48456,141 @@ Get a model response 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](https://platform.openai.com/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 }` @@ -47835,9 +48600,272 @@ Get a model response 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 }` @@ -47877,6 +48905,472 @@ Get a model response 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 - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `Compaction object { id, encrypted_content, type, 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. @@ -48438,67 +49932,6 @@ Get a model response 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. @@ -48617,6 +50050,67 @@ Get a model response 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. @@ -48675,11 +50169,9 @@ Get a model response 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` @@ -48704,29 +50196,22 @@ Get a model response - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + 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"` + - `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. @@ -48759,1058 +50244,946 @@ Get a model response - `"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` + - `usage: BetaResponseUsage` - 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. + Token accounting for the compaction pass, including cached, reasoning, and total tokens. - - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` + - `input_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. - - `BetaToolChoiceOptions = "none" or "auto" or "required"` + - `input_tokens_details: object { cache_write_tokens, cached_tokens }` - Controls which (if any) tool is called by the model. + A detailed breakdown of the input tokens. - `none` means the model will not call any tool and instead generates a message. + - `cache_write_tokens: number` - `auto` means the model can pick between generating a message or calling one or - more tools. + The number of input tokens that were written to the cache. - `required` means the model must call one or more tools. + - `cached_tokens: number` - - `"none"` + The number of tokens that were retrieved from the cache. + [More on prompt caching](/docs/guides/prompt-caching). - - `"auto"` + - `output_tokens: number` - - `"required"` + The number of output tokens. - - `BetaToolChoiceAllowed object { mode, tools, type }` + - `output_tokens_details: object { reasoning_tokens }` - Constrains the tools available to the model to a pre-defined set. + A detailed breakdown of the output tokens. - - `mode: "auto" or "required"` + - `reasoning_tokens: number` - Constrains the tools available to the model to a pre-defined set. + The number of reasoning tokens. - `auto` allows the model to pick from among the allowed tools and generate a - message. + - `total_tokens: number` - `required` requires the model to call one or more of the allowed tools. + The total number of tokens used. - - `"auto"` +### Example - - `"required"` +```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" + }' +``` - - `tools: array of map[unknown]` +#### Response - A list of tool definitions that the model should be allowed to call. +```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 + } +} +``` - For the Responses API, the list of tool definitions might look like: +### Example - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } +```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" + } ] - ``` - - - `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](https://platform.openai.com/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](https://platform.openai.com/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](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/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](https://platform.openai.com/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](https://platform.openai.com/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"` +#### Response - The type of the function tool. Always `function`. +```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 + }, + "output_tokens": 438, + "output_tokens_details": { + "reasoning_tokens": 64 + }, + "total_tokens": 577 + } +} +``` - - `"function"` +## Domain Types - - `allowed_callers: optional array of "direct" or "programmatic"` +### Beta Compacted Response - The tool invocation context(s). +- `BetaCompactedResponse object { id, created_at, object, 2 more }` - - `"direct"` + - `id: string` - - `"programmatic"` + The unique identifier for the compacted response. - - `defer_loading: optional boolean` + - `created_at: number` - Whether this function is deferred and loaded via tool search. + Unix timestamp (in seconds) when the compacted conversation was created. - - `description: optional string` + - `object: "response.compaction"` - A description of the function. Used by the model to determine whether or not to call the function. + The object type. Always `response.compaction`. - - `output_schema: optional map[unknown]` + - `"response.compaction"` - A JSON schema object describing the JSON value encoded in string outputs for this 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` - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + The compacted list of output items. - 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 object { id, content, role, 4 more }` - - `type: "file_search"` + A message to or from the model. - The type of the file search tool. Always `file_search`. + - `id: string` - - `"file_search"` + The unique ID of the message. - - `vector_store_ids: array of string` + - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` - The IDs of the vector stores to search. + The content of the message - - `filters: optional object { key, type, value } or object { filters, type }` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - A filter to apply. + A text input to the model. - - `ComparisonFilter object { key, type, value }` + - `text: string` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The text input to the model. - - `key: string` + - `type: "input_text"` - The key to compare against the value. + The type of the input item. Always `input_text`. - - `type: "eq" or "ne" or "gt" or 5 more` + - `"input_text"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `prompt_cache_breakpoint: optional object { mode }` - - `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 + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `"eq"` + - `mode: "explicit"` - - `"ne"` + The breakpoint mode. Always `explicit`. - - `"gt"` + - `"explicit"` - - `"gte"` + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - - `"lt"` + A text output from the model. - - `"lte"` + - `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 }` - - `"in"` + The annotations of the text output. - - `"nin"` + - `FileCitation object { file_id, filename, index, type }` - - `value: string or number or boolean or array of string or number` + A citation to a file. - The value to compare against the attribute key; supports string, number, or boolean types. + - `file_id: string` - - `string` + The ID of the file. - - `number` + - `filename: string` - - `boolean` + The filename of the file cited. - - `array of string or number` + - `index: number` - - `string` + The index of the file in the list of files. - - `number` + - `type: "file_citation"` - - `CompoundFilter object { filters, type }` + The type of the file citation. Always `file_citation`. - Combine multiple filters using `and` or `or`. + - `"file_citation"` - - `filters: array of object { key, type, value } or unknown` + - `URLCitation object { end_index, start_index, title, 2 more }` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + A citation for a web resource used to generate a model response. - - `ComparisonFilter object { key, type, value }` + - `end_index: number` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The index of the last character of the URL citation in the message. - - `key: string` + - `start_index: number` - The key to compare against the value. + The index of the first character of the URL citation in the message. - - `type: "eq" or "ne" or "gt" or 5 more` + - `title: string` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The title 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 + - `type: "url_citation"` - - `"eq"` + The type of the URL citation. Always `url_citation`. - - `"ne"` + - `"url_citation"` - - `"gt"` + - `url: string` - - `"gte"` + The URL of the web resource. - - `"lt"` + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - - `"lte"` + A citation for a container file used to generate a model response. - - `"in"` + - `container_id: string` - - `"nin"` + The ID of the container file. - - `value: string or number or boolean or array of string or number` + - `end_index: number` - The value to compare against the attribute key; supports string, number, or boolean types. + The index of the last character of the container file citation in the message. - - `string` + - `file_id: string` - - `number` + The ID of the file. - - `boolean` + - `filename: string` - - `array of string or number` + The filename of the container file cited. - - `string` + - `start_index: number` - - `number` + The index of the first character of the container file citation in the message. - - `unknown` + - `type: "container_file_citation"` - - `type: "and" or "or"` + The type of the container file citation. Always `container_file_citation`. - Type of operation: `and` or `or`. + - `"container_file_citation"` - - `"and"` + - `FilePath object { file_id, index, type }` - - `"or"` + A path to a file. - - `max_num_results: optional number` + - `file_id: string` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + The ID of the file. - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `index: number` - Ranking options for search. + The index of the file in the list of files. - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `type: "file_path"` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + The type of the file path. Always `file_path`. - - `embedding_weight: number` + - `"file_path"` - The weight of the embedding in the reciprocal ranking fusion. + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - - `text_weight: number` + - `token: string` - The weight of the text in the reciprocal ranking fusion. + - `bytes: array of number` - - `ranker: optional "auto" or "default-2024-11-15"` + - `logprob: number` - The ranker to use for the file search. + - `top_logprobs: array of object { token, bytes, logprob }` - - `"auto"` + - `token: string` - - `"default-2024-11-15"` + - `bytes: array of number` - - `score_threshold: optional number` + - `logprob: 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. + - `text: string` - - `Computer object { type }` + The text output 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). + - `type: "output_text"` - - `type: "computer"` + The type of the output text. Always `output_text`. - The type of the computer tool. Always `computer`. + - `"output_text"` - - `"computer"` + - `Text object { text, type }` - - `ComputerUsePreview object { display_height, display_width, environment, type }` + A text content. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `text: string` - - `display_height: number` + - `type: "text"` - The height of the computer display. + - `"text"` - - `display_width: number` + - `SummaryText object { text, type }` - The width of the computer display. + A summary text from the model. - - `environment: "windows" or "mac" or "linux" or 2 more` + - `text: string` - The type of computer environment to control. + A summary of the reasoning output from the model so far. - - `"windows"` + - `type: "summary_text"` - - `"mac"` + The type of the object. Always `summary_text`. - - `"linux"` + - `"summary_text"` - - `"ubuntu"` + - `ReasoningText object { text, type }` - - `"browser"` + Reasoning text from the model. - - `type: "computer_use_preview"` + - `text: string` - The type of the computer use tool. Always `computer_use_preview`. + The reasoning text from the model. - - `"computer_use_preview"` + - `type: "reasoning_text"` - - `WebSearch object { type, filters, search_context_size, user_location }` + The type of the reasoning text. Always `reasoning_text`. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `"reasoning_text"` - - `type: "web_search" or "web_search_2025_08_26"` + - `BetaResponseOutputRefusal object { refusal, type }` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + A refusal from the model. - - `"web_search"` + - `refusal: string` - - `"web_search_2025_08_26"` + The refusal explanation from the model. - - `filters: optional object { allowed_domains }` + - `type: "refusal"` - Filters for the search. + The type of the refusal. Always `refusal`. - - `allowed_domains: optional array of string` + - `"refusal"` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `search_context_size: optional "low" or "medium" or "high"` + - `detail: "low" or "high" or "auto" or "original"` - 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 detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - `"low"` - - `"medium"` - - `"high"` - - `user_location: optional object { city, country, region, 2 more }` + - `"auto"` - The approximate location of the user. + - `"original"` - - `city: optional string` + - `type: "input_image"` - Free text input for the city of the user, e.g. `San Francisco`. + The type of the input item. Always `input_image`. - - `country: optional string` + - `"input_image"` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `file_id: optional string` - - `region: optional string` + The ID of the file to be sent to the model. - Free text input for the region of the user, e.g. `California`. + - `image_url: optional string` - - `timezone: 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 [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `prompt_cache_breakpoint: optional object { mode }` - - `type: optional "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. - The type of location approximation. Always `approximate`. + - `mode: "explicit"` - - `"approximate"` + The breakpoint mode. Always `explicit`. - - `Mcp object { server_label, type, allowed_callers, 9 more }` + - `"explicit"` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` - - `server_label: string` + A screenshot of a computer. - A label for this MCP server, used to identify it in tool calls. + - `detail: "low" or "high" or "auto" or "original"` - - `type: "mcp"` + 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 MCP tool. Always `mcp`. + - `"low"` - - `"mcp"` + - `"high"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"auto"` - The tool invocation context(s). + - `"original"` - - `"direct"` + - `file_id: 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: string` - List of allowed tool names or a filter object. + The URL of the screenshot image. - - `McpAllowedTools = array of string` + - `type: "computer_screenshot"` - A string array of allowed tool names + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `McpToolFilter object { read_only, tool_names }` + - `"computer_screenshot"` - A filter object to specify which tools are allowed. + - `prompt_cache_breakpoint: optional object { mode }` - - `read_only: optional boolean` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - 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. + - `mode: "explicit"` - - `tool_names: optional array of string` + The breakpoint mode. Always `explicit`. - List of allowed tool names. + - `"explicit"` - - `authorization: optional string` + - `BetaResponseInputFile object { type, detail, file_data, 4 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. + A file input to the model. - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + - `type: "input_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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + The type of the input item. Always `input_file`. - Currently supported `connector_id` values are: + - `"input_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` + - `detail: optional "auto" or "low" or "high"` - - `"connector_dropbox"` + 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`. - - `"connector_gmail"` + - `"auto"` - - `"connector_googlecalendar"` + - `"low"` - - `"connector_googledrive"` + - `"high"` - - `"connector_microsoftteams"` + - `file_data: optional string` - - `"connector_outlookcalendar"` + The content of the file to be sent to the model. - - `"connector_outlookemail"` + - `file_id: optional string` - - `"connector_sharepoint"` + The ID of the file to be sent to the model. - - `defer_loading: optional boolean` + - `file_url: optional string` - Whether this MCP tool is deferred and discovered via tool search. + The URL of the file to be sent to the model. - - `headers: optional map[string]` + - `filename: optional string` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + The name of the file to be sent to the model. - - `require_approval: optional object { always, never } or "always" or "never"` + - `prompt_cache_breakpoint: optional object { mode }` - Specify which of the MCP server's tools require approval. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `McpToolApprovalFilter object { always, never }` + - `mode: "explicit"` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + The breakpoint mode. Always `explicit`. - - `always: optional object { read_only, tool_names }` + - `"explicit"` - A filter object to specify which tools are allowed. + - `EncryptedContent object { encrypted_content, type }` - - `read_only: optional boolean` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - 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. + - `encrypted_content: string` - - `tool_names: optional array of string` + Opaque encrypted content. - List of allowed tool names. + - `type: "encrypted_content"` - - `never: optional object { read_only, tool_names }` + The type of the input item. Always `encrypted_content`. - A filter object to specify which tools are allowed. + - `"encrypted_content"` - - `read_only: optional boolean` + - `role: "unknown" or "user" or "assistant" or 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. + The role of the message. One of `unknown`, `user`, `assistant`, `system`, `critic`, `discriminator`, `developer`, or `tool`. - - `tool_names: optional array of string` + - `"unknown"` - List of allowed tool names. + - `"user"` - - `McpToolApprovalSetting = "always" or "never"` + - `"assistant"` - 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. + - `"system"` - - `"always"` + - `"critic"` - - `"never"` + - `"discriminator"` - - `server_description: optional string` + - `"developer"` - Optional description of the MCP server, used to provide more context. + - `"tool"` - - `server_url: optional string` + - `status: "in_progress" or "completed" or "incomplete"` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + The status of item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - `tunnel_id: optional string` + - `"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. + - `"completed"` - - `CodeInterpreter object { container, type, allowed_callers }` + - `"incomplete"` - A tool that runs Python code to help generate a response to a prompt. + - `type: "message"` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + The type of the message. Always set to `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. + - `"message"` - - `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"` + - `phase: optional "commentary" or "final_answer"` - Always `auto`. + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - `"auto"` + - `"commentary"` - - `file_ids: optional array of string` + - `"final_answer"` - An optional list of uploaded files to make available to your code. + - `Program object { id, call_id, code, 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 program item. - - `"1g"` + - `call_id: string` - - `"4g"` + The stable call ID of the program item. - - `"16g"` + - `code: string` - - `"64g"` + The JavaScript source executed by programmatic tool calling. - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `fingerprint: string` - Network access policy for the container. + Opaque program replay fingerprint that must be round-tripped. - - `BetaContainerNetworkPolicyDisabled object { type }` + - `type: "program"` - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + The type of the item. Always `program`. - - `type: "code_interpreter"` + - `"program"` - The type of the code interpreter tool. Always `code_interpreter`. + - `agent: optional object { agent_name }` - - `"code_interpreter"` + 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"` + - `ProgramOutput object { id, call_id, result, 3 more }` - - `"programmatic"` + - `id: string` - - `ProgrammaticToolCalling object { type }` + The unique ID of the program output item. - - `type: "programmatic_tool_calling"` + - `call_id: string` - The type of the tool. Always `programmatic_tool_calling`. + The call ID of the program item. - - `"programmatic_tool_calling"` + - `result: string` - - `ImageGeneration object { type, action, background, 9 more }` + The result produced by the program item. - A tool that generates images using the GPT image models. + - `status: "completed" or "incomplete"` - - `type: "image_generation"` + The terminal status of the program output item. - The type of the image generation tool. Always `image_generation`. + - `"completed"` - - `"image_generation"` + - `"incomplete"` - - `action: optional "generate" or "edit" or "auto"` + - `type: "program_output"` - Whether to generate a new image or edit an existing image. Default: `auto`. + The type of the item. Always `program_output`. - - `"generate"` + - `"program_output"` - - `"edit"` + - `agent: optional object { agent_name }` - - `"auto"` + The agent that produced this item. - - `background: optional "transparent" or "opaque" or "auto"` + - `agent_name: string` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + The canonical name of the agent that produced this item. - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + - `FunctionCall object { arguments, call_id, name, 6 more }` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. - - `"transparent"` + - `arguments: string` - - `"opaque"` + A JSON string of the arguments to pass to the function. - - `"auto"` + - `call_id: string` - - `input_fidelity: optional "high" or "low"` + The unique ID of the function tool call generated by 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`. + - `name: string` - - `"high"` + The name of the function to run. - - `"low"` + - `type: "function_call"` - - `input_image_mask: optional object { file_id, image_url }` + The type of the function tool call. Always `function_call`. - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `"function_call"` - - `file_id: optional string` + - `id: optional string` - File ID for the mask image. + The unique ID of the function tool 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-2" or 3 more` + - `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-2" or 3 more` + 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-2"` + - `Program object { caller_id, type }` - - `"gpt-image-2-2026-04-21"` + - `caller_id: string` - - `"gpt-image-1.5"` + The call ID of the program item that produced this tool call. - - `"chatgpt-image-latest"` + - `type: "program"` - - `moderation: optional "auto" or "low"` + - `"program"` - Moderation level for the generated image. Default: `auto`. + - `namespace: optional string` - - `"auto"` + The namespace of the function to run. - - `"low"` + - `status: optional "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"` + - `MultiAgentCall object { id, action, arguments, 3 more }` - - `"webp"` + - `id: string` - - `"jpeg"` + The unique ID of the multi-agent call item. - - `partial_images: optional number` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + The multi-agent action to execute. - - `quality: optional "low" or "medium" or "high" or "auto"` + - `"spawn_agent"` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `"interrupt_agent"` - - `"low"` + - `"list_agents"` - - `"medium"` + - `"send_message"` - - `"high"` + - `"followup_task"` - - `"auto"` + - `"wait_agent"` - - `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`. + The JSON string of arguments generated for the action. - - `string` + - `call_id: string` - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + The unique ID linking this call to its output. - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `type: "multi_agent_call"` - - `"1024x1024"` + The type of the multi-agent call. Always `multi_agent_call`. - - `"1024x1536"` + - `"multi_agent_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"` + - `MultiAgentCallOutput object { id, action, call_id, 3 more }` - The type of the local shell tool. Always `local_shell`. + - `id: string` - - `"local_shell"` + The unique ID of the multi-agent call output item. - - `Shell object { type, allowed_callers, environment }` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - A tool that allows the model to execute shell commands. + The multi-agent action that produced this result. - - `type: "shell"` + - `"spawn_agent"` - The type of the shell tool. Always `shell`. + - `"interrupt_agent"` - - `"shell"` + - `"list_agents"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"send_message"` - The tool invocation context(s). + - `"followup_task"` - - `"direct"` + - `"wait_agent"` - - `"programmatic"` + - `call_id: string` - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + The unique ID of the multi-agent call. - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `output: array of BetaResponseOutputText` - - `BetaLocalEnvironment object { type, skills }` + Text output returned by the multi-agent action. - - `BetaContainerReference object { container_id, type }` + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` - - `Custom object { name, type, allowed_callers, 3 more }` + The annotations of the text output. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - - `name: string` + - `text: string` - The name of the custom tool, used to identify it in tool calls. + The text output from the model. - - `type: "custom"` + - `type: "output_text"` - The type of the custom tool. Always `custom`. + The type of the output text. Always `output_text`. - - `"custom"` + - `type: "multi_agent_call_output"` - - `allowed_callers: optional array of "direct" or "programmatic"` + The type of the multi-agent result. Always `multi_agent_call_output`. - The tool invocation context(s). + - `"multi_agent_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` + - `ToolSearchCall object { id, arguments, call_id, 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 tool search call item. - The input format for the custom tool. Default is unconstrained text. + - `arguments: unknown` - - `Text object { type }` + Arguments used for the tool search call. - Unconstrained free-form text. + - `call_id: string` - - `type: "text"` + The unique ID of the tool search call generated by the model. - Unconstrained text format. Always `text`. + - `execution: "server" or "client"` - - `"text"` + Whether tool search was executed by the server or by the client. - - `Grammar object { definition, syntax, type }` + - `"server"` - A grammar defined by the user. + - `"client"` - - `definition: string` + - `status: "in_progress" or "completed" or "incomplete"` - The grammar definition. + The status of the tool search call item that was recorded. - - `syntax: "lark" or "regex"` + - `"in_progress"` - The syntax of the grammar definition. One of `lark` or `regex`. + - `"completed"` - - `"lark"` + - `"incomplete"` - - `"regex"` + - `type: "tool_search_call"` - - `type: "grammar"` + The type of the item. Always `tool_search_call`. - Grammar format. Always `grammar`. + - `"tool_search_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. + - `created_by: optional string` - - `name: string` + The identifier of the actor that created the item. - The namespace name used in tool calls (for example, `crm`). + - `ToolSearchOutput object { id, call_id, execution, 5 more }` - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + - `id: string` - The function/custom tools available inside this namespace. + The unique ID of the tool search output item. - - `Function object { name, type, allowed_callers, 5 more }` + - `call_id: string` - - `name: string` + The unique ID of the tool search call generated by the model. - - `type: "function"` + - `execution: "server" or "client"` - - `"function"` + Whether tool search was executed by the server or by the client. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"server"` - The tool invocation context(s). + - `"client"` - - `"direct"` + - `status: "in_progress" or "completed" or "incomplete"` - - `"programmatic"` + The status of the tool search output item that was recorded. - - `defer_loading: optional boolean` + - `"in_progress"` - Whether this function should be deferred and discovered via tool search. + - `"completed"` - - `description: optional string` + - `"incomplete"` - - `output_schema: optional map[unknown]` + - `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 JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + The loaded tool definitions returned by tool search. - - `parameters: optional unknown` + - `Function object { name, parameters, strict, 5 more }` - - `strict: optional boolean` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - 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. + - `name: string` - - `Custom object { name, type, allowed_callers, 3 more }` + The name of the function to call. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `parameters: map[unknown]` - - `name: string` + A JSON schema object describing the parameters of the function. - The name of the custom tool, used to identify it in tool calls. + - `strict: boolean` - - `type: "custom"` + Whether strict parameter validation is enforced for this function tool. - The type of the custom tool. Always `custom`. + - `type: "function"` - - `"custom"` + The type of the function tool. Always `function`. + + - `"function"` - `allowed_callers: optional array of "direct" or "programmatic"` @@ -49822,2717 +51195,2448 @@ Get a model response - `defer_loading: optional boolean` - Whether this tool should be deferred and discovered via tool search. + Whether this function is deferred and loaded 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 }` + A description of the function. Used by the model to determine whether or not to call the function. - Unconstrained free-form text. + - `output_schema: optional map[unknown]` - - `type: "text"` + A JSON schema object describing the JSON value encoded in string outputs for this function. - Unconstrained text format. Always `text`. + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - - `"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). - - `Grammar object { definition, syntax, type }` + - `type: "file_search"` - A grammar defined by the user. + The type of the file search tool. Always `file_search`. - - `definition: string` + - `"file_search"` - The grammar definition. + - `vector_store_ids: array of string` - - `syntax: "lark" or "regex"` + The IDs of the vector stores to search. - The syntax of the grammar definition. One of `lark` or `regex`. + - `filters: optional object { key, type, value } or object { filters, type }` - - `"lark"` + A filter to apply. - - `"regex"` + - `ComparisonFilter object { key, type, value }` - - `type: "grammar"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - Grammar format. Always `grammar`. + - `key: string` - - `"grammar"` + The key to compare against the value. - - `type: "namespace"` + - `type: "eq" or "ne" or "gt" or 5 more` - The type of the tool. Always `namespace`. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `"namespace"` + - `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 - - `ToolSearch object { type, description, execution, parameters }` + - `"eq"` - Hosted or BYOT tool search configuration for deferred tools. + - `"ne"` - - `type: "tool_search"` + - `"gt"` - The type of the tool. Always `tool_search`. + - `"gte"` - - `"tool_search"` + - `"lt"` - - `description: optional string` + - `"lte"` - Description shown to the model for a client-executed tool search tool. + - `"in"` - - `execution: optional "server" or "client"` + - `"nin"` - Whether tool search is executed by the server or by the client. + - `value: string or number or boolean or array of string or number` - - `"server"` + The value to compare against the attribute key; supports string, number, or boolean types. - - `"client"` + - `string` - - `parameters: optional unknown` + - `number` - Parameter schema for a client-executed tool search tool. + - `boolean` - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + - `array of string or 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). + - `string` - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `number` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `CompoundFilter object { filters, type }` - - `"web_search_preview"` + Combine multiple filters using `and` or `or`. - - `"web_search_preview_2025_03_11"` + - `filters: array of object { key, type, value } or unknown` - - `search_content_types: optional array of "text" or "image"` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `"text"` + - `ComparisonFilter object { key, type, value }` - - `"image"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `search_context_size: optional "low" or "medium" or "high"` + - `key: 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 key to compare against the value. - - `"low"` + - `type: "eq" or "ne" or "gt" or 5 more` - - `"medium"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `"high"` + - `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_location: optional object { type, city, country, 2 more }` + - `"eq"` - The user's location. + - `"ne"` - - `type: "approximate"` + - `"gt"` - The type of location approximation. Always `approximate`. + - `"gte"` - - `"approximate"` + - `"lt"` - - `city: optional string` + - `"lte"` - Free text input for the city of the user, e.g. `San Francisco`. + - `"in"` - - `country: optional string` + - `"nin"` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `value: string or number or boolean or array of string or number` - - `region: optional string` + The value to compare against the attribute key; supports string, number, or boolean types. - Free text input for the region of the user, e.g. `California`. + - `string` - - `timezone: optional string` + - `number` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `boolean` - - `ApplyPatch object { type, allowed_callers }` + - `array of string or number` - Allows the assistant to create, delete, or update files using unified diffs. + - `string` - - `type: "apply_patch"` + - `number` - The type of the tool. Always `apply_patch`. + - `unknown` - - `"apply_patch"` + - `type: "and" or "or"` - - `allowed_callers: optional array of "direct" or "programmatic"` + Type of operation: `and` or `or`. - The tool invocation context(s). + - `"and"` - - `"direct"` + - `"or"` - - `"programmatic"` + - `max_num_results: optional number` - - `top_p: number` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - 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. + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - We generally recommend altering this or `temperature` but not both. + Ranking options for search. - - `background: optional boolean` + - `hybrid_search: optional object { embedding_weight, text_weight }` - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `completed_at: optional number` + - `embedding_weight: number` - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + The weight of the embedding in the reciprocal ranking fusion. - - `conversation: optional object { id }` + - `text_weight: number` - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + The weight of the text in the reciprocal ranking fusion. - - `id: string` + - `ranker: optional "auto" or "default-2024-11-15"` - The unique ID of the conversation that this response was associated with. + The ranker to use for the file search. - - `max_output_tokens: optional number` + - `"auto"` - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + - `"default-2024-11-15"` - - `max_tool_calls: optional number` + - `score_threshold: 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. + 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. - - `moderation: optional object { input, output }` + - `Computer object { type }` - Moderation results for the response input and output, if moderated completions were requested. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + - `type: "computer"` - Moderation for the response input. + The type of the computer tool. Always `computer`. - - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` + - `"computer"` - A moderation result produced for the response input or output. + - `ComputerUsePreview object { display_height, display_width, environment, type }` - - `categories: map[boolean]` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `display_height: number` - - `category_applied_input_types: map[array of "text" or "image"]` + The height of the computer display. - Which modalities of input are reflected by the score for each category. + - `display_width: number` - - `"text"` + The width of the computer display. - - `"image"` + - `environment: "windows" or "mac" or "linux" or 2 more` - - `category_scores: map[number]` + The type of computer environment to control. - A dictionary of moderation categories to scores. + - `"windows"` - - `flagged: boolean` + - `"mac"` - A boolean indicating whether the content was flagged by any category. + - `"linux"` - - `model: string` + - `"ubuntu"` - The moderation model that produced this result. + - `"browser"` - - `type: "moderation_result"` + - `type: "computer_use_preview"` - The object type, which was always `moderation_result` for successful moderation results. + The type of the computer use tool. Always `computer_use_preview`. - - `"moderation_result"` + - `"computer_use_preview"` - - `Error object { code, message, type }` + - `WebSearch object { type, filters, search_context_size, user_location }` - An error produced while attempting moderation for the response input or output. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - - `code: string` + - `type: "web_search" or "web_search_2025_08_26"` - The error code. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `message: string` + - `"web_search"` - The error message. + - `"web_search_2025_08_26"` - - `type: "error"` + - `filters: optional object { allowed_domains }` - The object type, which was always `error` for moderation failures. + Filters for the search. - - `"error"` + - `allowed_domains: optional array of string` - - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - Moderation for the response output. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` + - `search_context_size: optional "low" or "medium" or "high"` - A moderation result produced for the response input or output. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `categories: map[boolean]` + - `"low"` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `"medium"` - - `category_applied_input_types: map[array of "text" or "image"]` + - `"high"` - Which modalities of input are reflected by the score for each category. + - `user_location: optional object { city, country, region, 2 more }` - - `"text"` + The approximate location of the user. - - `"image"` + - `city: optional string` - - `category_scores: map[number]` + Free text input for the city of the user, e.g. `San Francisco`. - A dictionary of moderation categories to scores. + - `country: optional string` - - `flagged: boolean` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - A boolean indicating whether the content was flagged by any category. + - `region: optional string` - - `model: string` + Free text input for the region of the user, e.g. `California`. - The moderation model that produced this result. + - `timezone: optional string` - - `type: "moderation_result"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The object type, which was always `moderation_result` for successful moderation results. + - `type: optional "approximate"` - - `"moderation_result"` + The type of location approximation. Always `approximate`. - - `Error object { code, message, type }` + - `"approximate"` - An error produced while attempting moderation for the response input or output. + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `code: string` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - The error code. + - `server_label: string` - - `message: string` + A label for this MCP server, used to identify it in tool calls. - The error message. + - `type: "mcp"` - - `type: "error"` + The type of the MCP tool. Always `mcp`. - The object type, which was always `error` for moderation failures. + - `"mcp"` - - `"error"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `previous_response_id: optional string` + The tool invocation context(s). - The unique ID of the previous response to the model. Use this to - create multi-turn conversations. Learn more about - [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + - `"direct"` - - `prompt: optional BetaResponsePrompt` + - `"programmatic"` - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `id: string` + List of allowed tool names or a filter object. - The unique identifier of the prompt template to use. + - `McpAllowedTools = array of string` - - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` + A string array of allowed tool names - 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. + - `McpToolFilter object { read_only, tool_names }` - - `string` + 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. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `tool_names: optional array of string` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + List of allowed tool names. - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `authorization: optional string` - A file input to the model. + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - - `version: optional string` + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - Optional version of the prompt template. + 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). - - `prompt_cache_key: optional string` + Currently supported `connector_id` values are: - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + - 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` - - `prompt_cache_options: optional object { mode, ttl }` + - `"connector_dropbox"` - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + - `"connector_gmail"` - - `mode: "implicit" or "explicit"` + - `"connector_googlecalendar"` - Whether implicit prompt-cache breakpoints were enabled. + - `"connector_googledrive"` - - `"implicit"` + - `"connector_microsoftteams"` - - `"explicit"` + - `"connector_outlookcalendar"` - - `ttl: "30m"` + - `"connector_outlookemail"` - The minimum lifetime applied to each cache breakpoint. + - `"connector_sharepoint"` - - `"30m"` + - `defer_loading: optional boolean` - - `prompt_cache_retention: optional "in_memory" or "24h"` + Whether this MCP tool is deferred and discovered via tool search. - Deprecated. Use `prompt_cache_options.ttl` instead. + - `headers: optional map[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](https://platform.openai.com/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. + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + - `require_approval: optional object { always, never } or "always" or "never"` - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + Specify which of the MCP server's tools require approval. - - `"in_memory"` + - `McpToolApprovalFilter object { always, never }` - - `"24h"` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `reasoning: optional object { context, effort, generate_summary, 2 more }` + - `always: optional object { read_only, tool_names }` - **gpt-5 and o-series models only** + A filter object to specify which tools are allowed. - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + - `read_only: optional boolean` - - `context: optional "auto" or "current_turn" or "all_turns"` + 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. - Controls which reasoning items are rendered back to the model on later turns. - When returned on a response, this is the effective reasoning context mode - used for the response. + - `tool_names: optional array of string` - - `"auto"` + List of allowed tool names. - - `"current_turn"` + - `never: optional object { read_only, tool_names }` - - `"all_turns"` + A filter object to specify which tools are allowed. - - `effort: optional "none" or "minimal" or "low" or 4 more` + - `read_only: optional boolean` - 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. + 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. - - `"none"` + - `tool_names: optional array of string` - - `"minimal"` + List of allowed tool names. - - `"low"` + - `McpToolApprovalSetting = "always" or "never"` - - `"medium"` + 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. - - `"high"` + - `"always"` - - `"xhigh"` + - `"never"` - - `"max"` + - `server_description: optional string` - - `generate_summary: optional "auto" or "concise" or "detailed"` + Optional description of the MCP server, used to provide more context. - **Deprecated:** use `summary` instead. + - `server_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 for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `"auto"` + - `tunnel_id: optional string` - - `"concise"` + 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. - - `"detailed"` + - `CodeInterpreter object { container, type, allowed_callers }` - - `mode: optional string or "standard" or "pro"` + A tool that runs Python code to help generate a response to a prompt. - Controls the reasoning execution mode for the request. + - `container: string or object { type, file_ids, memory_limit, network_policy }` - When returned on a response, this is the effective execution mode. + 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` - - `"standard" or "pro"` - - Controls the reasoning execution mode for the request. + The container ID. - When returned on a response, this is the effective execution mode. + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - - `"standard"` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `"pro"` + - `type: "auto"` - - `summary: optional "auto" or "concise" or "detailed"` + Always `auto`. - 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` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + - `file_ids: optional array of string` - - `"auto"` + An optional list of uploaded files to make available to your code. - - `"concise"` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `"detailed"` + The memory limit for the code interpreter container. - - `safety_identifier: optional string` + - `"1g"` - 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](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `"4g"` - - `service_tier: optional "auto" or "default" or "flex" or 2 more` + - `"16g"` - Specifies the processing type used for serving the request. + - `"64g"` - - 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](https://platform.openai.com/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'. + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - 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. + Network access policy for the container. - - `"auto"` + - `BetaContainerNetworkPolicyDisabled object { type }` - - `"default"` + - `type: "disabled"` - - `"flex"` + Disable outbound network access. Always `disabled`. - - `"scale"` + - `"disabled"` - - `"priority"` + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `status: optional BetaResponseStatus` + - `allowed_domains: array of string` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + A list of allowed domains when type is `allowlist`. - - `"completed"` + - `type: "allowlist"` - - `"failed"` + Allow outbound network access only to specified domains. Always `allowlist`. - - `"in_progress"` + - `"allowlist"` - - `"cancelled"` + - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` - - `"queued"` + Optional domain-scoped secrets for allowlisted domains. - - `"incomplete"` + - `domain: string` - - `text: optional BetaResponseTextConfig` + The domain associated with the secret. - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + - `name: string` - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + The name of the secret to inject for the domain. - - `format: optional BetaResponseFormatTextConfig` + - `value: string` - An object specifying the format that the model must output. + The secret value to inject for the domain. - Configuring `{ "type": "json_schema" }` enables Structured Outputs, - which ensures the model will match your supplied JSON schema. Learn more in the - [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `type: "code_interpreter"` - The default format is `{ "type": "text" }` with no additional options. + The type of the code interpreter tool. Always `code_interpreter`. - **Not recommended for gpt-4o and newer models:** + - `"code_interpreter"` - 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. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `Text object { type }` + The tool invocation context(s). - Default response format. Used to generate text responses. + - `"direct"` - - `type: "text"` + - `"programmatic"` - The type of response format being defined. Always `text`. + - `ProgrammaticToolCalling object { type }` - - `"text"` + - `type: "programmatic_tool_calling"` - - `BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` + The type of the tool. Always `programmatic_tool_calling`. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `"programmatic_tool_calling"` - - `name: string` + - `ImageGeneration object { type, action, background, 9 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. + A tool that generates images using the GPT image models. - - `schema: map[unknown]` + - `type: "image_generation"` - 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 image generation tool. Always `image_generation`. - - `type: "json_schema"` + - `"image_generation"` - The type of response format being defined. Always `json_schema`. + - `action: optional "generate" or "edit" or "auto"` - - `"json_schema"` + Whether to generate a new image or edit an existing image. Default: `auto`. - - `description: optional string` + - `"generate"` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `"edit"` - - `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](https://platform.openai.com/docs/guides/structured-outputs). + - `background: optional "transparent" or "opaque" or "auto"` - - `JSONObject object { type }` + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - 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. + - `"transparent"` - - `type: "json_object"` + - `"opaque"` - The type of response format being defined. Always `json_object`. + - `"auto"` - - `"json_object"` + - `input_fidelity: optional "high" or "low"` - - `verbosity: optional "low" or "medium" or "high"` + 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`. - 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`. + - `"high"` - `"low"` - - `"medium"` + - `input_image_mask: optional object { file_id, image_url }` - - `"high"` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `top_logprobs: optional number` + - `file_id: optional 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. + File ID for the mask image. - - `truncation: optional "auto" or "disabled"` + - `image_url: optional string` - The truncation strategy to use for the model response. + Base64-encoded mask image. - - `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. + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `"auto"` + The image generation model to use. Default: `gpt-image-1`. - - `"disabled"` + - `string` - - `usage: optional BetaResponseUsage` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + The image generation model to use. Default: `gpt-image-1`. - - `input_tokens: number` + - `"gpt-image-1"` - The number of input tokens. + - `"gpt-image-1-mini"` - - `input_tokens_details: object { cache_write_tokens, cached_tokens }` + - `"gpt-image-1.5"` - A detailed breakdown of the input tokens. + - `moderation: optional "auto" or "low"` - - `cache_write_tokens: number` + Moderation level for the generated image. Default: `auto`. - The number of input tokens that were written to the cache. + - `"auto"` - - `cached_tokens: number` + - `"low"` - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + - `output_compression: optional number` - - `output_tokens: number` + Compression level for the output image. Default: 100. - The number of output tokens. + - `output_format: optional "png" or "webp" or "jpeg"` - - `output_tokens_details: object { reasoning_tokens }` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - A detailed breakdown of the output tokens. + - `"png"` - - `reasoning_tokens: number` + - `"webp"` - The number of reasoning tokens. + - `"jpeg"` - - `total_tokens: number` + - `partial_images: optional number` - The total number of tokens used. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `user: optional string` + - `quality: optional "low" or "medium" or "high" or "auto"` - 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](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. -### Example + - `"low"` -```http -curl https://api.openai.com/v1/responses/$RESPONSE_ID \ - -H 'OpenAI-Beta: assistants=v2' \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + - `"medium"` -#### Response + - `"high"` -```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" - } - ], - "text": "text", - "type": "output_text", - "logprobs": [ - { - "token": "token", - "bytes": [ - 0 - ], - "logprob": 0, - "top_logprobs": [ - { - "token": "token", - "bytes": [ - 0 - ], - "logprob": 0 - } - ] - } - ] - } - ], - "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" -} -``` + - `"auto"` -### Example + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` -```http -curl https://api.openai.com/v1/responses/resp_123 \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + 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 + - `string` -```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 - }, - "output_tokens": 18, - "output_tokens_details": { - "reasoning_tokens": 0 - }, - "total_tokens": 50 - }, - "user": null, - "metadata": {} -} -``` + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` -## Delete a model 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`. -**delete** `/responses/{response_id}?beta=true` + - `"1024x1024"` -Delete a model response + - `"1024x1536"` -### Path Parameters + - `"1536x1024"` -- `response_id: string` + - `"auto"` -### Header Parameters + - `LocalShell object { type }` -- `"openai-beta": optional array of "responses_multi_agent=v1"` + A tool that allows the model to execute shell commands in a local environment. - - `"responses_multi_agent=v1"` + - `type: "local_shell"` -### Example + The type of the local shell tool. Always `local_shell`. -```http -curl https://api.openai.com/v1/responses/$RESPONSE_ID \ - -X DELETE \ - -H 'OpenAI-Beta: assistants=v2' \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + - `"local_shell"` -### Example + - `Shell object { type, allowed_callers, environment }` -```http -curl -X DELETE https://api.openai.com/v1/responses/resp_123 \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + A tool that allows the model to execute shell commands. -#### Response + - `type: "shell"` -```json -{ - "id": "resp_6786a1bec27481909a17d673315b29f6", - "object": "response", - "deleted": true -} -``` + The type of the shell tool. Always `shell`. -## Cancel a response + - `"shell"` -**post** `/responses/{response_id}/cancel?beta=true` + - `allowed_callers: optional array of "direct" or "programmatic"` -Cancel a response + The tool invocation context(s). -### Path Parameters + - `"direct"` -- `response_id: string` + - `"programmatic"` -### Header Parameters + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` -- `"openai-beta": optional array of "responses_multi_agent=v1"` + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - - `"responses_multi_agent=v1"` + - `type: "container_auto"` -### Returns + Automatically creates a container for this request -- `BetaResponse object { id, created_at, error, 31 more }` + - `"container_auto"` - - `id: string` + - `file_ids: optional array of string` - Unique identifier for this Response. + An optional list of uploaded files to make available to your code. - - `created_at: number` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - Unix timestamp (in seconds) of when this Response was created. + The memory limit for the container. - - `error: BetaResponseError` + - `"1g"` - An error object returned when the model fails to generate a Response. + - `"4g"` - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 16 more` + - `"16g"` - The error code for the response. + - `"64g"` - - `"server_error"` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `"rate_limit_exceeded"` + Network access policy for the container. - - `"invalid_prompt"` + - `BetaContainerNetworkPolicyDisabled object { type }` - - `"bio_policy"` + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `"vector_store_timeout"` + - `skills: optional array of BetaSkillReference or BetaInlineSkill` - - `"invalid_image"` + An optional list of skills referenced by id or inline data. - - `"invalid_image_format"` + - `BetaSkillReference object { skill_id, type, version }` - - `"invalid_base64_image"` + - `skill_id: string` - - `"invalid_image_url"` + The ID of the referenced skill. - - `"image_too_large"` + - `type: "skill_reference"` - - `"image_too_small"` + References a skill created with the /v1/skills endpoint. - - `"image_parse_error"` + - `"skill_reference"` - - `"image_content_policy_violation"` + - `version: optional string` - - `"invalid_image_mode"` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `"image_file_too_large"` + - `BetaInlineSkill object { description, name, source, type }` - - `"unsupported_image_media_type"` + - `description: string` - - `"empty_image_file"` + The description of the skill. - - `"failed_to_download_image"` + - `name: string` - - `"image_file_not_found"` + The name of the skill. - - `message: string` + - `source: BetaInlineSkillSource` - A human-readable description of the error. + Inline skill payload - - `incomplete_details: object { reason }` + - `data: string` - Details about why the response is incomplete. + Base64-encoded skill zip bundle. - - `reason: optional "max_output_tokens" or "content_filter"` + - `media_type: "application/zip"` - The reason why the response is incomplete. + The media type of the inline skill payload. Must be `application/zip`. - - `"max_output_tokens"` + - `"application/zip"` - - `"content_filter"` + - `type: "base64"` - - `instructions: string or array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + The type of the inline skill source. Must be `base64`. - A system (or developer) message inserted into the model's context. + - `"base64"` - 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: "inline"` - - `string` + Defines an inline skill for this request. - A text input to the model, equivalent to a text input with the - `developer` role. + - `"inline"` - - `InputItemList = array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + - `BetaLocalEnvironment object { type, skills }` - A list of one or many input items to the model, containing - different content types. + - `type: "local"` - - `BetaEasyInputMessage object { content, role, phase, type }` + Use a local computer 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. Messages with the - `assistant` role are presumed to have been generated by the model in previous - interactions. + - `"local"` - - `content: string or BetaResponseInputMessageContentList` + - `skills: optional array of BetaLocalSkill` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + An optional list of skills. - - `TextInput = string` + - `description: string` - A text input to the model. + The description of the skill. - - `BetaResponseInputMessageContentList = array of BetaResponseInputContent` + - `name: string` - A list of one or many input items to the model, containing different content - types. + The name of the skill. - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `path: string` - A text input to the model. + The path to the directory containing the skill. - - `text: string` + - `BetaContainerReference object { container_id, type }` - The text input to the model. + - `container_id: string` - - `type: "input_text"` + The ID of the referenced container. - The type of the input item. Always `input_text`. + - `type: "container_reference"` - - `"input_text"` + References a container created with the /v1/containers endpoint - - `prompt_cache_breakpoint: optional object { mode }` + - `"container_reference"` - Marks the exact end of a reusable 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](https://platform.openai.com/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"` + - `Namespace object { description, name, tools, type }` - - `file_data: optional string` + Groups function/custom tools under a shared namespace. - The content of the file to be sent to the model. + - `description: string` - - `file_id: optional string` + A description of the namespace shown to the model. - The ID of the file to be sent to the model. + - `name: string` - - `file_url: optional string` + The namespace name used in tool calls (for example, `crm`). - The URL of the file to be sent to the model. + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - - `filename: optional string` + The function/custom tools available inside this namespace. - The name of the file to be sent to the model. + - `Function object { name, type, allowed_callers, 5 more }` - - `prompt_cache_breakpoint: optional object { mode }` + - `name: string` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `type: "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 "assistant" or "system" or "developer"` + - `"direct"` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + - `"programmatic"` - - `"user"` + - `defer_loading: optional boolean` - - `"assistant"` + Whether this function should be deferred and discovered via tool search. - - `"system"` + - `description: optional string` - - `"developer"` + - `output_schema: optional map[unknown]` - - `phase: optional "commentary" or "final_answer"` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + - `parameters: optional unknown` - - `"commentary"` + - `strict: optional boolean` - - `"final_answer"` + 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: optional "message"` + - `Custom object { name, type, allowed_callers, 3 more }` - The type of the message input. Always `message`. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `"message"` + - `name: string` - - `Message object { content, role, agent, 2 more }` + The name of the custom tool, used to identify it in tool calls. - 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: "custom"` - - `content: BetaResponseInputMessageContentList` + The type of the custom tool. Always `custom`. - A list of one or many input items to the model, containing different content - types. + - `"custom"` - - `role: "user" or "system" or "developer"` + - `allowed_callers: optional array of "direct" or "programmatic"` - The role of the message input. One of `user`, `system`, or `developer`. + The tool invocation context(s). - - `"user"` + - `"direct"` - - `"system"` + - `"programmatic"` - - `"developer"` + - `defer_loading: optional boolean` - - `agent: optional object { agent_name }` + Whether this tool should be deferred and discovered via tool search. - The agent that produced this item. + - `description: optional string` - - `agent_name: string` + Optional description of the custom tool, used to provide more context. - The canonical name of the agent that produced this item. + - `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 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: optional "message"` + - `"text"` - The type of the message input. Always set to `message`. + - `Grammar object { definition, syntax, type }` - - `"message"` + A grammar defined by the user. - - `BetaResponseOutputMessage object { id, content, role, 4 more }` + - `definition: string` - An output message from the model. + The grammar definition. - - `id: string` + - `syntax: "lark" or "regex"` - The unique ID of the output message. + The syntax of the grammar definition. One of `lark` or `regex`. - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + - `"lark"` - The content of the output message. + - `"regex"` - - `BetaResponseOutputText object { annotations, text, type, logprobs }` + - `type: "grammar"` - A text output from the model. + Grammar format. Always `grammar`. - - `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 }` + - `"grammar"` - The annotations of the text output. + - `type: "namespace"` - - `FileCitation object { file_id, filename, index, type }` + The type of the tool. Always `namespace`. - A citation to a file. + - `"namespace"` - - `file_id: string` + - `ToolSearch object { type, description, execution, parameters }` - The ID of the file. + Hosted or BYOT tool search configuration for deferred tools. - - `filename: string` + - `type: "tool_search"` - The filename of the file cited. + The type of the tool. Always `tool_search`. - - `index: number` + - `"tool_search"` + + - `description: optional string` + + Description shown to the model for a client-executed tool search tool. - The index of the file in the list of files. + - `execution: optional "server" or "client"` - - `type: "file_citation"` + Whether tool search is executed by the server or by the client. - The type of the file citation. Always `file_citation`. + - `"server"` - - `"file_citation"` + - `"client"` - - `URLCitation object { end_index, start_index, title, 2 more }` + - `parameters: optional unknown` - A citation for a web resource used to generate a model response. + Parameter schema for a client-executed tool search tool. - - `end_index: number` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - The index of the last character of the URL citation in the 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). - - `start_index: number` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - The index of the first character of the URL citation in the message. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `title: string` + - `"web_search_preview"` - The title of the web resource. + - `"web_search_preview_2025_03_11"` - - `type: "url_citation"` + - `search_content_types: optional array of "text" or "image"` - The type of the URL citation. Always `url_citation`. + - `"text"` - - `"url_citation"` + - `"image"` - - `url: string` + - `search_context_size: optional "low" or "medium" or "high"` - The URL of the web resource. + 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. - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + - `"low"` - A citation for a container file used to generate a model response. + - `"medium"` - - `container_id: string` + - `"high"` - The ID of the container file. + - `user_location: optional object { type, city, country, 2 more }` - - `end_index: number` + The user's location. - The index of the last character of the container file citation in the message. + - `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 container file cited. + Free text input for the city of the user, e.g. `San Francisco`. - - `start_index: number` + - `country: optional string` - The index of the first character of the container file citation in the message. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `type: "container_file_citation"` + - `region: optional string` - The type of the container file citation. Always `container_file_citation`. + Free text input for the region of the user, e.g. `California`. - - `"container_file_citation"` + - `timezone: optional string` - - `FilePath object { file_id, index, type }` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - A path to a file. + - `ApplyPatch object { type, allowed_callers }` - - `file_id: string` + Allows the assistant to create, delete, or update files using unified diffs. - The ID of the file. + - `type: "apply_patch"` - - `index: number` + The type of the tool. Always `apply_patch`. - The index of the file in the list of files. + - `"apply_patch"` - - `type: "file_path"` + - `allowed_callers: optional array of "direct" or "programmatic"` - The type of the file path. Always `file_path`. + The tool invocation context(s). - - `"file_path"` + - `"direct"` - - `text: string` + - `"programmatic"` - The text output from the model. + - `type: "tool_search_output"` - - `type: "output_text"` + The type of the item. Always `tool_search_output`. - The type of the output text. Always `output_text`. + - `"tool_search_output"` - - `"output_text"` + - `agent: optional object { agent_name }` - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + The agent that produced this item. - - `token: string` + - `agent_name: string` - - `bytes: array of number` + The canonical name of the agent that produced this item. - - `logprob: number` + - `created_by: optional string` - - `top_logprobs: array of object { token, bytes, logprob }` + The identifier of the actor that created the item. - - `token: string` + - `AdditionalTools object { id, role, tools, 2 more }` - - `bytes: array of number` + - `id: string` - - `logprob: number` + The unique ID of the additional tools item. - - `BetaResponseOutputRefusal object { refusal, type }` + - `role: "unknown" or "user" or "assistant" or 5 more` - A refusal from the model. + The role that provided the additional tools. - - `refusal: string` + - `"unknown"` - The refusal explanation from the model. + - `"user"` - - `type: "refusal"` + - `"assistant"` - The type of the refusal. Always `refusal`. + - `"system"` - - `"refusal"` + - `"critic"` - - `role: "assistant"` + - `"discriminator"` - The role of the output message. Always `assistant`. + - `"developer"` - - `"assistant"` + - `"tool"` - - `status: "in_progress" or "completed" or "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 status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + The additional tool definitions made available at this item. - - `"in_progress"` + - `Function object { name, parameters, strict, 5 more }` - - `"completed"` + 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). - - `"incomplete"` + - `name: string` - - `type: "message"` + The name of the function to call. - The type of the output message. Always `message`. + - `parameters: map[unknown]` - - `"message"` + A JSON schema object describing the parameters of the function. - - `agent: optional object { agent_name }` + - `strict: boolean` - The agent that produced this item. + 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`. - - `phase: optional "commentary" or "final_answer"` + - `"function"` - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"commentary"` + The tool invocation context(s). - - `"final_answer"` + - `"direct"` - - `FileSearchCall object { id, queries, status, 3 more }` + - `"programmatic"` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `defer_loading: optional boolean` - - `id: string` + Whether this function is deferred and loaded via tool search. - The unique ID of the file search tool call. + - `description: optional string` - - `queries: array of string` + A description of the function. Used by the model to determine whether or not to call the function. - The queries used to search for files. + - `output_schema: optional map[unknown]` - - `status: "in_progress" or "searching" or "completed" or 2 more` + A JSON schema object describing the JSON value encoded in string outputs for this function. - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - - `"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). - - `"searching"` + - `type: "file_search"` - - `"completed"` + The type of the file search tool. Always `file_search`. - - `"incomplete"` + - `"file_search"` - - `"failed"` + - `vector_store_ids: array of string` - - `type: "file_search_call"` + The IDs of the vector stores to search. - The type of the file search tool call. Always `file_search_call`. + - `filters: optional object { key, type, value } or object { filters, type }` - - `"file_search_call"` + A filter to apply. - - `agent: optional object { agent_name }` + - `ComparisonFilter object { key, type, value }` - The agent that produced this item. + 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. - - `results: optional array of object { attributes, file_id, filename, 2 more }` + - `type: "eq" or "ne" or "gt" or 5 more` - The results of the file search tool call. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `attributes: optional map[string or number or boolean]` + - `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 - 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. + - `"eq"` - - `string` + - `"ne"` - - `number` + - `"gt"` - - `boolean` + - `"gte"` - - `file_id: optional string` + - `"lt"` - The unique ID of the file. + - `"lte"` - - `filename: optional string` + - `"in"` - The name of the file. + - `"nin"` - - `score: optional number` + - `value: string or number or boolean or array of string or number` - The relevance score of the file - a value between 0 and 1. + The value to compare against the attribute key; supports string, number, or boolean types. - - `text: optional string` + - `string` - The text that was retrieved from the file. + - `number` - - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` + - `boolean` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + - `array of string or number` - - `id: string` + - `string` - The unique ID of the computer call. + - `number` - - `call_id: string` + - `CompoundFilter object { filters, type }` - An identifier used when responding to the tool call with output. + Combine multiple filters using `and` or `or`. - - `pending_safety_checks: array of object { id, code, message }` + - `filters: array of object { key, type, value } or unknown` - The pending safety checks for the computer call. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `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"` + - `unknown` - - `"forward"` + - `type: "and" or "or"` - - `type: "click"` + Type of operation: `and` or `or`. - Specifies the event type. For a click action, this property is always `click`. + - `"and"` - - `"click"` + - `"or"` - - `x: number` + - `max_num_results: optional number` - The x-coordinate where the click occurred. + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `y: number` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - The y-coordinate where the click occurred. + Ranking options for search. - - `keys: optional array of string` + - `hybrid_search: optional object { embedding_weight, text_weight }` - The keys being held while clicking. + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `DoubleClick object { keys, type, x, y }` + - `embedding_weight: number` - A double click action. + The weight of the embedding in the reciprocal ranking fusion. - - `keys: array of string` + - `text_weight: number` - The keys being held while double-clicking. + The weight of the text in the reciprocal ranking fusion. - - `type: "double_click"` + - `ranker: optional "auto" or "default-2024-11-15"` - Specifies the event type. For a double click action, this property is always set to `double_click`. + The ranker to use for the file search. - - `"double_click"` + - `"auto"` - - `x: number` + - `"default-2024-11-15"` - The x-coordinate where the double click occurred. + - `score_threshold: optional number` - - `y: number` + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - The y-coordinate where the double click occurred. + - `Computer object { type }` - - `Drag object { path, type, keys }` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - A drag action. + - `type: "computer"` - - `path: array of object { x, y }` + The type of the computer tool. Always `computer`. - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `"computer"` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `ComputerUsePreview object { display_height, display_width, environment, type }` - - `x: number` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The x-coordinate. + - `display_height: number` - - `y: number` + The height of the computer display. - The y-coordinate. + - `display_width: number` - - `type: "drag"` + The width of the computer display. - Specifies the event type. For a drag action, this property is always set to `drag`. + - `environment: "windows" or "mac" or "linux" or 2 more` - - `"drag"` + The type of computer environment to control. - - `keys: optional array of string` + - `"windows"` - The keys being held while dragging the mouse. + - `"mac"` - - `Keypress object { keys, type }` + - `"linux"` - A collection of keypresses the model would like to perform. + - `"ubuntu"` - - `keys: array of string` + - `"browser"` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `type: "computer_use_preview"` - - `type: "keypress"` + The type of the computer use tool. Always `computer_use_preview`. - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `"computer_use_preview"` - - `"keypress"` + - `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"` - - `type: "move"` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - Specifies the event type. For a move action, this property is always set to `move`. + - `"web_search"` - - `"move"` + - `"web_search_2025_08_26"` - - `x: number` + - `filters: optional object { allowed_domains }` - The x-coordinate to move to. + Filters for the search. - - `y: number` + - `allowed_domains: optional array of string` - The y-coordinate to move to. + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `keys: optional array of string` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - The keys being held while moving the mouse. + - `search_context_size: optional "low" or "medium" or "high"` - - `Screenshot 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 screenshot action. + - `"low"` - - `type: "screenshot"` + - `"medium"` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `"high"` - - `"screenshot"` + - `user_location: optional object { city, country, region, 2 more }` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + The approximate location of the user. - A scroll action. + - `city: optional string` - - `scroll_x: number` + Free text input for the city of the user, e.g. `San Francisco`. - The horizontal scroll distance. + - `country: optional string` - - `scroll_y: number` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The vertical scroll distance. + - `region: optional string` - - `type: "scroll"` + Free text input for the region of the user, e.g. `California`. - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `timezone: optional string` - - `"scroll"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `x: number` + - `type: optional "approximate"` - The x-coordinate where the scroll occurred. + The type of location approximation. Always `approximate`. - - `y: number` + - `"approximate"` - The y-coordinate where the scroll occurred. + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `keys: optional 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). - The keys being held while scrolling. + - `server_label: string` - - `Type object { text, type }` + A label for this MCP server, used to identify it in tool calls. - An action to type in text. + - `type: "mcp"` - - `text: string` + The type of the MCP tool. Always `mcp`. - The text to type. + - `"mcp"` - - `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. + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `type: "wait"` + List of allowed tool names or a filter object. - Specifies the event type. For a wait action, this property is always set to `wait`. + - `McpAllowedTools = array of string` - - `"wait"` + A string array of allowed tool names - - `actions: optional BetaComputerActionList` + - `McpToolFilter object { read_only, tool_names }` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + A filter object to specify which tools are allowed. - - `Click object { button, type, x, 2 more }` + - `read_only: optional boolean` - A click action. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `DoubleClick object { keys, type, x, y }` + - `tool_names: optional array of string` - A double click action. + List of allowed tool names. - - `Drag object { path, type, keys }` + - `authorization: optional string` - A drag action. + 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. - - `Keypress object { keys, type }` + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - A collection of keypresses the model would like to perform. + 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). - - `Move object { type, x, y, keys }` + Currently supported `connector_id` values are: - A mouse move action. + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - - `Screenshot object { type }` + - `"connector_dropbox"` - A screenshot action. + - `"connector_gmail"` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `"connector_googlecalendar"` - A scroll action. + - `"connector_googledrive"` - - `Type object { text, type }` + - `"connector_microsoftteams"` - An action to type in text. + - `"connector_outlookcalendar"` - - `Wait object { type }` + - `"connector_outlookemail"` - A wait action. + - `"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. - - `ComputerCallOutput object { call_id, output, type, 4 more }` + - `require_approval: optional object { always, never } or "always" or "never"` - The output of a computer tool call. + Specify which of the MCP server's tools require approval. - - `call_id: string` + - `McpToolApprovalFilter object { always, never }` - The ID of the computer tool call that produced the 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. - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `always: optional object { read_only, tool_names }` - A computer screenshot image used with the computer use tool. + A filter object to specify which tools are allowed. - - `type: "computer_screenshot"` + - `read_only: optional boolean` - Specifies the event type. For a computer screenshot, this property is - always set to `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. - - `"computer_screenshot"` + - `tool_names: optional array of string` - - `file_id: optional 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: optional string` + A filter object to specify which tools are allowed. - The URL of the screenshot image. + - `read_only: optional boolean` - - `type: "computer_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 computer tool call output. Always `computer_call_output`. + - `tool_names: optional array of string` - - `"computer_call_output"` + List of allowed tool names. - - `id: optional string` + - `McpToolApprovalSetting = "always" or "never"` - The ID of the computer tool call output. + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `"always"` - The safety checks reported by the API that have been acknowledged by the developer. + - `"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. - - `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. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `string` - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input 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"` - - `WebSearchCall object { id, action, status, 2 more }` + Always `auto`. - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `"auto"` - - `id: string` + - `file_ids: optional array of string` - The unique ID of the web search tool call. + An optional list of uploaded files to make available to your code. - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - 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 memory limit for the code interpreter container. - - `Search object { type, queries, query, sources }` + - `"1g"` - Action type "search" - Performs a web search query. + - `"4g"` - - `type: "search"` + - `"16g"` - The action type. + - `"64g"` - - `"search"` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `queries: optional array of string` + Network access policy for the container. - The search queries. + - `BetaContainerNetworkPolicyDisabled object { type }` - - `query: optional string` + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - The search query. + - `type: "code_interpreter"` - - `sources: optional array of object { type, url }` + The type of the code interpreter tool. Always `code_interpreter`. - The sources used in the search. + - `"code_interpreter"` - - `type: "url"` + - `allowed_callers: optional array of "direct" or "programmatic"` - The type of source. Always `url`. + The tool invocation context(s). - - `"url"` + - `"direct"` - - `url: string` + - `"programmatic"` - The URL of the source. + - `ProgrammaticToolCalling object { type }` - - `OpenPage object { type, url }` + - `type: "programmatic_tool_calling"` - Action type "open_page" - Opens a specific URL from search results. + The type of the tool. Always `programmatic_tool_calling`. - - `type: "open_page"` + - `"programmatic_tool_calling"` - The action type. + - `ImageGeneration object { type, action, background, 9 more }` - - `"open_page"` + A tool that generates images using the GPT image models. - - `url: optional string` + - `type: "image_generation"` - The URL opened by the model. + The type of the image generation tool. Always `image_generation`. - - `FindInPage object { pattern, type, url }` + - `"image_generation"` - Action type "find_in_page": Searches for a pattern within a loaded page. + - `action: optional "generate" or "edit" or "auto"` - - `pattern: string` + Whether to generate a new image or edit an existing image. Default: `auto`. - The pattern or text to search for within the page. + - `"generate"` - - `type: "find_in_page"` + - `"edit"` - The action type. + - `"auto"` - - `"find_in_page"` + - `background: optional "transparent" or "opaque" or "auto"` - - `url: string` + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - The URL of the page searched for the pattern. + - `"transparent"` - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `"opaque"` - The status of the web search tool call. + - `"auto"` - - `"in_progress"` + - `input_fidelity: optional "high" or "low"` - - `"searching"` + 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"` - - `"failed"` + - `"low"` - - `type: "web_search_call"` + - `input_image_mask: optional object { file_id, image_url }` - The type of the web search tool call. Always `web_search_call`. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `"web_search_call"` + - `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"` - - `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](https://platform.openai.com/docs/guides/function-calling) for more information. + - `string` - - `arguments: string` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - A JSON string of the arguments to pass to the function. + The image generation model to use. Default: `gpt-image-1`. - - `call_id: string` + - `"gpt-image-1"` - The unique ID of the function tool call generated by the model. + - `"gpt-image-1-mini"` - - `name: string` + - `"gpt-image-1.5"` - The name of the function to run. + - `moderation: optional "auto" or "low"` - - `type: "function_call"` + Moderation level for the generated image. Default: `auto`. - The type of the function tool call. Always `function_call`. + - `"auto"` - - `"function_call"` + - `"low"` - - `id: optional string` + - `output_compression: optional number` - The unique ID of the function tool call. + Compression level for the output image. Default: 100. - - `agent: optional object { agent_name }` + - `output_format: optional "png" or "webp" or "jpeg"` - The agent that produced this item. + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `agent_name: string` + - `"png"` - The canonical name of the agent that produced this item. + - `"webp"` - - `caller: optional object { type } or object { caller_id, type }` + - `"jpeg"` - The execution context that produced this tool call. + - `partial_images: optional number` - - `Direct object { type }` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `type: "direct"` + - `quality: optional "low" or "medium" or "high" or "auto"` - - `"direct"` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `Program object { caller_id, type }` + - `"low"` - - `caller_id: string` + - `"medium"` - The call ID of the program item that produced this tool call. + - `"high"` - - `type: "program"` + - `"auto"` - - `"program"` + - `size: optional string or "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. + - `string` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"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"` + - `"1024x1024"` - - `"completed"` + - `"1024x1536"` - - `"incomplete"` + - `"1536x1024"` - - `FunctionCallOutput object { call_id, output, type, 4 more }` + - `"auto"` - The output of a function tool call. + - `LocalShell object { type }` - - `call_id: string` + A tool that allows the model to execute shell commands in a local environment. - The unique ID of the function tool call generated by the model. + - `type: "local_shell"` - - `output: string or BetaResponseFunctionCallOutputItemList` + The type of the local shell tool. Always `local_shell`. - Text, image, or file output of the function tool call. + - `"local_shell"` - - `string` + - `Shell object { type, allowed_callers, environment }` - A JSON string of the output of the function tool call. + A tool that allows the model to execute shell commands. - - `BetaResponseFunctionCallOutputItemList = array of BetaResponseFunctionCallOutputItem` + - `type: "shell"` - An array of content outputs (text, image, file) for the function tool call. + The type of the shell tool. Always `shell`. - - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` + - `"shell"` - A text input to the model. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `text: string` + The tool invocation context(s). - The text input to the model. + - `"direct"` - - `type: "input_text"` + - `"programmatic"` - The type of the input item. Always `input_text`. + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - `"input_text"` + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - - `prompt_cache_breakpoint: optional object { mode }` + - `BetaLocalEnvironment object { type, skills }` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `BetaContainerReference object { container_id, type }` - - `mode: "explicit"` + - `Custom object { name, type, allowed_callers, 3 more }` - The breakpoint mode. Always `explicit`. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `"explicit"` + - `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](https://platform.openai.com/docs/guides/vision) + - `type: "custom"` - - `type: "input_image"` + The type of the custom tool. Always `custom`. - The type of the input item. Always `input_image`. + - `"custom"` - - `"input_image"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `detail: optional "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 tool should be deferred and discovered via tool search. - - `"original"` + - `description: optional string` - - `file_id: optional string` + Optional description of the custom tool, used to provide more context. - The ID of the file to be sent to the model. + - `format: optional object { type } or object { definition, syntax, type }` - - `image_url: optional string` + The input format for the custom tool. Default is unconstrained text. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `Text object { type }` - - `prompt_cache_breakpoint: optional object { mode }` + Unconstrained free-form text. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `type: "text"` - - `mode: "explicit"` + Unconstrained text format. Always `text`. - The breakpoint mode. Always `explicit`. + - `"text"` - - `"explicit"` + - `Grammar object { definition, syntax, type }` - - `BetaResponseInputFileContent object { type, detail, file_data, 4 more }` + A grammar defined by the user. - A file input to the model. + - `definition: string` - - `type: "input_file"` + The grammar definition. - The type of the input item. Always `input_file`. + - `syntax: "lark" or "regex"` - - `"input_file"` + The syntax of the grammar definition. One of `lark` or `regex`. - - `detail: optional "auto" or "low" or "high"` + - `"lark"` - 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`. + - `"regex"` - - `"auto"` + - `type: "grammar"` - - `"low"` + Grammar format. Always `grammar`. - - `"high"` + - `"grammar"` - - `file_data: optional string` + - `Namespace object { description, name, tools, type }` - The base64-encoded data of the file to be sent to the model. + Groups function/custom tools under a shared namespace. - - `file_id: optional string` + - `description: string` - The ID of the file to be sent to the model. + A description of the namespace shown to the model. - - `file_url: optional string` + - `name: string` - The URL of the file to be sent to the model. + The namespace name used in tool calls (for example, `crm`). - - `filename: optional string` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - The name of the file to be sent to the model. + The function/custom tools available inside this namespace. - - `prompt_cache_breakpoint: optional object { mode }` + - `Function object { name, type, allowed_callers, 5 more }` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `name: string` - - `mode: "explicit"` + - `type: "function"` - The breakpoint mode. Always `explicit`. + - `"function"` - - `"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` + - `defer_loading: optional boolean` - The unique ID of the function tool call output. Populated when this item is returned via API. + Whether this function should be deferred and discovered via tool search. - - `agent: optional object { agent_name }` + - `description: optional string` - The agent that produced this item. + - `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` - - `caller: optional object { type } or object { caller_id, type }` + - `strict: optional boolean` - The execution context that produced this tool 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. - - `Direct object { type }` + - `Custom object { name, type, allowed_callers, 3 more }` - - `type: "direct"` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - The caller type. Always `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"` - The caller type. Always `program`. + The tool invocation context(s). - - `"program"` + - `"direct"` - - `status: optional "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. - - `AgentMessage object { author, content, recipient, 3 more }` + - `format: optional object { type } or object { definition, syntax, type }` - A message routed between agents. + The input format for the custom tool. Default is unconstrained text. - - `author: string` + - `Text object { type }` - The sending agent identity. + Unconstrained free-form text. - - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` + - `type: "text"` - Plaintext, image, or encrypted content sent between agents. + Unconstrained text format. Always `text`. - - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` + - `"text"` - A text input to the model. + - `Grammar object { definition, syntax, type }` - - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` + A grammar defined by the user. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `definition: string` - - `EncryptedContent object { encrypted_content, type }` + The grammar definition. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `syntax: "lark" or "regex"` - - `encrypted_content: string` + The syntax of the grammar definition. One of `lark` or `regex`. - Opaque encrypted content. + - `"lark"` - - `type: "encrypted_content"` + - `"regex"` - The type of the input item. Always `encrypted_content`. + - `type: "grammar"` - - `"encrypted_content"` + Grammar format. Always `grammar`. - - `recipient: string` + - `"grammar"` - The destination agent identity. + - `type: "namespace"` - - `type: "agent_message"` + The type of the tool. Always `namespace`. - The item type. Always `agent_message`. + - `"namespace"` - - `"agent_message"` + - `ToolSearch object { type, description, execution, parameters }` - - `id: optional string` + Hosted or BYOT tool search configuration for deferred tools. - The unique ID of this agent message item. + - `type: "tool_search"` - - `agent: optional object { agent_name }` + The type of the tool. Always `tool_search`. - The agent that produced this item. + - `"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. - - `MultiAgentCall object { action, arguments, call_id, 3 more }` + - `execution: optional "server" or "client"` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + Whether tool search is executed by the server or by the client. - The multi-agent action that was executed. + - `"server"` - - `"spawn_agent"` + - `"client"` - - `"interrupt_agent"` + - `parameters: optional unknown` - - `"list_agents"` + Parameter schema for a client-executed tool search tool. - - `"send_message"` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - - `"followup_task"` + 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). - - `"wait_agent"` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `arguments: string` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - The action arguments as a JSON string. + - `"web_search_preview"` - - `call_id: string` + - `"web_search_preview_2025_03_11"` - The unique ID linking this call to its output. + - `search_content_types: optional array of "text" or "image"` - - `type: "multi_agent_call"` + - `"text"` - The item type. Always `multi_agent_call`. + - `"image"` - - `"multi_agent_call"` + - `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 unique ID of this multi-agent call. + - `"low"` - - `agent: optional object { agent_name }` + - `"medium"` - The agent that produced this item. + - `"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. - - `MultiAgentCallOutput object { action, call_id, output, 3 more }` + - `type: "approximate"` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + The type of location approximation. Always `approximate`. - The multi-agent action that produced this result. + - `"approximate"` - - `"spawn_agent"` + - `city: optional string` - - `"interrupt_agent"` + Free text input for the city of the user, e.g. `San Francisco`. - - `"list_agents"` + - `country: optional string` - - `"send_message"` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `"followup_task"` + - `region: optional string` - - `"wait_agent"` + Free text input for the region of the user, e.g. `California`. - - `call_id: string` + - `timezone: optional string` - The unique ID of the multi-agent call. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `output: array of object { text, type, annotations }` + - `ApplyPatch object { type, allowed_callers }` - Text output returned by the multi-agent action. + Allows the assistant to create, delete, or update files using unified diffs. - - `text: string` + - `type: "apply_patch"` - The text content. + The type of the tool. Always `apply_patch`. - - `type: "output_text"` + - `"apply_patch"` - The content type. Always `output_text`. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"output_text"` + The tool invocation context(s). - - `annotations: optional array of object { file_id, filename, index, type } or array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` + - `"direct"` - Citations associated with the text content. + - `"programmatic"` - - `array of object { file_id, filename, index, type }` + - `type: "additional_tools"` - - `file_id: string` + The type of the item. Always `additional_tools`. - The ID of the file. + - `"additional_tools"` - - `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"` + - `AgentMessage object { id, author, content, 3 more }` - The citation type. Always `file_citation`. + - `id: string` - - `"file_citation"` + The unique ID of the agent message. - - `array of object { end_index, start_index, title, 2 more }` + - `author: string` - - `end_index: number` + The sending agent identity. - The index of the last character of the citation in the message. + - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` - - `start_index: number` + Encrypted content sent between agents. - The index of the first character of the citation in the message. + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `title: string` + A text input to the model. - The title of the cited resource. + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - - `type: "url_citation"` + A text output from the model. - The citation type. Always `url_citation`. + - `Text object { text, type }` - - `"url_citation"` + A text content. - - `url: string` + - `text: string` - The URL of the cited resource. + - `type: "text"` - - `array of object { container_id, end_index, file_id, 3 more }` + - `"text"` - - `container_id: string` + - `SummaryText object { text, type }` - The ID of the container. + A summary text from the model. - - `end_index: number` + - `text: string` - The index of the last character of the citation in the message. + A summary of the reasoning output from the model so far. - - `file_id: string` + - `type: "summary_text"` - The ID of the container file. + The type of the object. Always `summary_text`. - - `filename: string` + - `"summary_text"` - The filename of the container file cited. + - `ReasoningText object { text, type }` - - `start_index: number` + Reasoning text from the model. - The index of the first character of the citation in the message. + - `text: string` - - `type: "container_file_citation"` + The reasoning text from the model. - The citation type. Always `container_file_citation`. + - `type: "reasoning_text"` - - `"container_file_citation"` + The type of the reasoning text. Always `reasoning_text`. - - `type: "multi_agent_call_output"` + - `"reasoning_text"` - The item type. Always `multi_agent_call_output`. + - `BetaResponseOutputRefusal object { refusal, type }` - - `"multi_agent_call_output"` + A refusal from the model. - - `id: optional string` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - The unique ID of this multi-agent call output. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `agent: optional object { agent_name }` + - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` - The agent that produced this item. + A screenshot of a computer. - - `agent_name: string` + - `detail: "low" or "high" or "auto" or "original"` - The canonical name of the agent that produced this item. + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `ToolSearchCall object { arguments, type, id, 4 more }` + - `"low"` - - `arguments: unknown` + - `"high"` - The arguments supplied to the tool search call. + - `"auto"` - - `type: "tool_search_call"` + - `"original"` - The item type. Always `tool_search_call`. + - `file_id: string` - - `"tool_search_call"` + The identifier of an uploaded file that contains the screenshot. - - `id: optional string` + - `image_url: string` - The unique ID of this tool 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 }` - - `call_id: optional string` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The unique ID of the tool search call generated by the model. + - `mode: "explicit"` - - `execution: optional "server" or "client"` + The breakpoint mode. Always `explicit`. - Whether tool search was executed by the server or by the client. + - `"explicit"` - - `"server"` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `"client"` + A file input to the model. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `EncryptedContent object { encrypted_content, type }` - The status of the tool search call. + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `"in_progress"` + - `encrypted_content: string` - - `"completed"` + Opaque encrypted content. - - `"incomplete"` + - `type: "encrypted_content"` - - `ToolSearchOutput object { tools, type, id, 4 more }` + The type of the input item. Always `encrypted_content`. - - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` + - `"encrypted_content"` - The loaded tool definitions returned by the tool search output. + - `recipient: string` - - `Function object { name, parameters, strict, 5 more }` + The destination agent identity. - 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: "agent_message"` - - `name: string` + The type of the item. Always `agent_message`. - The name of the function to call. + - `"agent_message"` - - `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"` + - `FunctionCallOutput object { call_id, output, type, 4 more }` - The type of the function tool. Always `function`. + The output of a function tool call. - - `"function"` + - `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). + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `"direct"` + The output from the function 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 function call. - Whether this function is deferred and loaded via tool search. + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `description: optional string` + Text, image, or file output of the function call. - A description of the function. Used by the model to determine whether or not to call the function. + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `output_schema: optional map[unknown]` + A text input to the model. - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `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: "function_call_output"` - - `"file_search"` + The type of the function tool call output. Always `function_call_output`. - - `vector_store_ids: array of string` + - `"function_call_output"` - The IDs of the vector stores to search. + - `id: optional string` - - `filters: optional object { key, type, value } or object { filters, type }` + The unique ID of the function tool call output. Populated when this item + is returned via API. - A filter to apply. + - `agent: optional object { agent_name }` - - `ComparisonFilter object { key, type, value }` + The agent that produced this item. - 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. + - `caller: optional object { type } or object { caller_id, type }` - - `type: "eq" or "ne" or "gt" or 5 more` + The execution context that produced this tool call. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `Direct object { 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 + - `type: "direct"` - - `"eq"` + The caller type. Always `direct`. - - `"ne"` + - `"direct"` - - `"gt"` + - `Program object { caller_id, type }` - - `"gte"` + - `caller_id: string` - - `"lt"` + The call ID of the program item that produced this tool call. - - `"lte"` + - `type: "program"` - - `"in"` + The caller type. Always `program`. - - `"nin"` + - `"program"` - - `value: string or number or boolean or array of string or number` + - `status: optional "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` + - `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. - - `number` + - `id: string` - - `CompoundFilter object { filters, type }` + The unique ID of the file search tool call. - Combine multiple filters using `and` or `or`. + - `queries: array of string` - - `filters: array of object { key, type, value } or unknown` + The queries used to search for files. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `status: "in_progress" or "searching" or "completed" or 2 more` - - `ComparisonFilter object { key, type, value }` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `"in_progress"` - - `key: string` + - `"searching"` - The key to compare against the value. + - `"completed"` - - `type: "eq" or "ne" or "gt" or 5 more` + - `"incomplete"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `"failed"` - - `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: "file_search_call"` - - `"eq"` + The type of the file search tool call. Always `file_search_call`. - - `"ne"` + - `"file_search_call"` - - `"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"` + - `results: optional array of object { attributes, file_id, filename, 2 more }` - - `"nin"` + The results of the file search tool call. - - `value: string or number or boolean or array of string or number` + - `attributes: optional map[string or number or boolean]` - The value to compare against the attribute key; supports string, number, or boolean types. + 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` @@ -52540,1003 +53644,984 @@ Cancel a response - `boolean` - - `array of string or number` + - `file_id: optional string` - - `string` + The unique ID of the file. - - `number` + - `filename: optional string` - - `unknown` + The name of the file. - - `type: "and" or "or"` + - `score: optional number` - Type of operation: `and` or `or`. + The relevance score of the file - a value between 0 and 1. - - `"and"` + - `text: optional string` - - `"or"` + The text that was retrieved from the file. - - `max_num_results: optional number` + - `WebSearchCall object { id, action, status, 2 more }` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `id: string` - Ranking options for search. + The unique ID of the web search tool call. - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + 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). - - `embedding_weight: number` + - `Search object { type, queries, query, sources }` - The weight of the embedding in the reciprocal ranking fusion. + Action type "search" - Performs a web search query. - - `text_weight: number` + - `type: "search"` - The weight of the text in the reciprocal ranking fusion. + The action type. - - `ranker: optional "auto" or "default-2024-11-15"` + - `"search"` - The ranker to use for the file search. + - `queries: optional array of string` - - `"auto"` + The search queries. - - `"default-2024-11-15"` + - `query: optional string` - - `score_threshold: optional number` + The search query. - 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. + - `sources: optional array of object { type, url }` - - `Computer object { type }` + The sources used in the search. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `type: "url"` - - `type: "computer"` + The type of source. Always `url`. - The type of the computer tool. Always `computer`. + - `"url"` - - `"computer"` + - `url: string` - - `ComputerUsePreview object { display_height, display_width, environment, type }` + The URL of the source. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `OpenPage object { type, url }` - - `display_height: number` + Action type "open_page" - Opens a specific URL from search results. - The height of the computer display. + - `type: "open_page"` - - `display_width: number` + The action type. - The width of the computer display. + - `"open_page"` - - `environment: "windows" or "mac" or "linux" or 2 more` + - `url: optional string` - The type of computer environment to control. + The URL opened by the model. - - `"windows"` + - `FindInPage object { pattern, type, url }` - - `"mac"` + Action type "find_in_page": Searches for a pattern within a loaded page. - - `"linux"` + - `pattern: string` - - `"ubuntu"` + The pattern or text to search for within the page. - - `"browser"` + - `type: "find_in_page"` - - `type: "computer_use_preview"` + The action type. - The type of the computer use tool. Always `computer_use_preview`. + - `"find_in_page"` - - `"computer_use_preview"` + - `url: string` - - `WebSearch object { type, filters, search_context_size, user_location }` + The URL of the page searched for the pattern. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `status: "in_progress" or "searching" or "completed" or "failed"` - - `type: "web_search" or "web_search_2025_08_26"` + The status of the web search tool call. - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `"in_progress"` - - `"web_search"` + - `"searching"` - - `"web_search_2025_08_26"` + - `"completed"` - - `filters: optional object { allowed_domains }` + - `"failed"` - Filters for the search. + - `type: "web_search_call"` - - `allowed_domains: optional array of string` + The type of the web search tool call. Always `web_search_call`. - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `"web_search_call"` - 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"` + - `ImageGenerationCall object { id, result, status, 2 more }` - - `"high"` + An image generation request made by the model. - - `user_location: optional object { city, country, region, 2 more }` + - `id: string` - The approximate location of the user. + The unique ID of the image generation call. - - `city: optional string` + - `result: string` - Free text input for the city of the user, e.g. `San Francisco`. + The generated image encoded in base64. - - `country: optional string` + - `status: "in_progress" or "completed" or "generating" or "failed"` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The status of the image generation call. - - `region: optional string` + - `"in_progress"` - Free text input for the region of the user, e.g. `California`. + - `"completed"` - - `timezone: optional string` + - `"generating"` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `"failed"` - - `type: optional "approximate"` + - `type: "image_generation_call"` - The type of location approximation. Always `approximate`. + The type of the image generation call. Always `image_generation_call`. - - `"approximate"` + - `"image_generation_call"` - - `Mcp object { server_label, type, allowed_callers, 9 more }` + - `agent: optional object { agent_name }` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + The agent that produced this item. - - `server_label: string` + - `agent_name: string` - A label for this MCP server, used to identify it in tool calls. + The canonical name of the agent that produced this item. - - `type: "mcp"` + - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` - The type of the MCP tool. Always `mcp`. + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - - `"mcp"` + - `id: string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The unique ID of the computer call. - The tool invocation context(s). + - `call_id: string` - - `"direct"` + An identifier used when responding to the tool call with output. - - `"programmatic"` + - `pending_safety_checks: array of object { id, code, message }` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + The pending safety checks for the computer call. - List of allowed tool names or a filter object. + - `id: string` - - `McpAllowedTools = array of string` + The ID of the pending safety check. - A string array of allowed tool names + - `code: optional string` - - `McpToolFilter object { read_only, tool_names }` + The type of the pending safety check. - A filter object to specify which tools are allowed. + - `message: optional string` - - `read_only: optional boolean` + Details about the pending safety check. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `status: "in_progress" or "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"` - - `authorization: optional string` + - `"completed"` - 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. + - `"incomplete"` - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + - `type: "computer_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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + The type of the computer call. Always `computer_call`. - Currently supported `connector_id` values are: + - `"computer_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` + - `action: optional BetaComputerAction` - - `"connector_dropbox"` + A click action. - - `"connector_gmail"` + - `Click object { button, type, x, 2 more }` - - `"connector_googlecalendar"` + A click action. - - `"connector_googledrive"` + - `button: "left" or "right" or "wheel" or 2 more` - - `"connector_microsoftteams"` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `"connector_outlookcalendar"` + - `"left"` - - `"connector_outlookemail"` + - `"right"` - - `"connector_sharepoint"` + - `"wheel"` - - `defer_loading: optional boolean` + - `"back"` - Whether this MCP tool is deferred and discovered via tool search. + - `"forward"` - - `headers: optional map[string]` + - `type: "click"` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + Specifies the event type. For a click action, this property is always `click`. - - `require_approval: optional object { always, never } or "always" or "never"` + - `"click"` - Specify which of the MCP server's tools require approval. + - `x: number` - - `McpToolApprovalFilter object { always, never }` + The x-coordinate where the click occurred. - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `y: number` - - `always: optional object { read_only, tool_names }` + The y-coordinate where the 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` - - `never: optional object { read_only, tool_names }` + The keys being held while double-clicking. - A filter object to specify which tools are allowed. + - `type: "double_click"` - - `read_only: optional boolean` + Specifies the event type. For a double click action, this property is always set to `double_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. + - `"double_click"` - - `tool_names: optional array of string` + - `x: number` - List of allowed tool names. + The x-coordinate where the double click occurred. - - `McpToolApprovalSetting = "always" or "never"` + - `y: number` - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + The y-coordinate where the double click occurred. - - `"always"` + - `Drag object { path, type, keys }` - - `"never"` + A drag action. - - `server_description: optional string` + - `path: array of object { x, y }` - Optional description of the MCP server, used to provide more context. + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `server_url: optional string` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `x: number` - - `tunnel_id: optional string` + The x-coordinate. - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. + - `y: number` - - `CodeInterpreter object { container, type, allowed_callers }` + The y-coordinate. - A tool that runs Python code to help generate a response to a prompt. + - `type: "drag"` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + Specifies the event type. For a drag action, this property is always set to `drag`. - 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. + - `"drag"` - - `string` + - `keys: optional array of string` - The container ID. + The keys being held while dragging the mouse. - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + - `Keypress object { keys, type }` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + A collection of keypresses the model would like to perform. - - `type: "auto"` + - `keys: array of string` - Always `auto`. + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `"auto"` + - `type: "keypress"` - - `file_ids: optional array of string` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - An optional list of uploaded files to make available to your code. + - `"keypress"` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `Move object { type, x, y, keys }` - The memory limit for the code interpreter container. + A mouse move action. - - `"1g"` + - `type: "move"` - - `"4g"` + Specifies the event type. For a move action, this property is always set to `move`. - - `"16g"` + - `"move"` - - `"64g"` + - `x: number` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + The x-coordinate to move to. - Network access policy for the container. + - `y: number` - - `BetaContainerNetworkPolicyDisabled object { type }` + The y-coordinate to move to. - - `type: "disabled"` + - `keys: optional array of string` - Disable outbound network access. Always `disabled`. + The keys being held while moving the mouse. - - `"disabled"` + - `Screenshot object { type }` - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + A screenshot action. - - `allowed_domains: array of string` + - `type: "screenshot"` - A list of allowed domains when type is `allowlist`. + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `type: "allowlist"` + - `"screenshot"` - Allow outbound network access only to specified domains. Always `allowlist`. + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - - `"allowlist"` + A scroll action. - - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` + - `scroll_x: number` - Optional domain-scoped secrets for allowlisted domains. + The horizontal scroll distance. - - `domain: string` + - `scroll_y: number` - The domain associated with the secret. + The vertical scroll distance. - - `name: string` + - `type: "scroll"` - The name of the secret to inject for the domain. + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `value: string` + - `"scroll"` - The secret value to inject for the domain. + - `x: number` - - `type: "code_interpreter"` + The x-coordinate where the scroll occurred. - The type of the code interpreter tool. Always `code_interpreter`. + - `y: number` - - `"code_interpreter"` + The y-coordinate where the scroll occurred. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `keys: optional array of string` - The tool invocation context(s). + The keys being held while scrolling. - - `"direct"` + - `Type object { text, type }` - - `"programmatic"` + An action to type in text. - - `ProgrammaticToolCalling object { type }` + - `text: string` - - `type: "programmatic_tool_calling"` + The text to type. - The type of the tool. Always `programmatic_tool_calling`. + - `type: "type"` - - `"programmatic_tool_calling"` + Specifies the event type. For a type action, this property is always set to `type`. - - `ImageGeneration object { type, action, background, 9 more }` + - `"type"` - A tool that generates images using the GPT image models. + - `Wait object { type }` - - `type: "image_generation"` + A wait action. - The type of the image generation tool. Always `image_generation`. + - `type: "wait"` - - `"image_generation"` + Specifies the event type. For a wait action, this property is always set to `wait`. - - `action: optional "generate" or "edit" or "auto"` + - `"wait"` - Whether to generate a new image or edit an existing image. Default: `auto`. + - `actions: optional BetaComputerActionList` - - `"generate"` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `"edit"` + - `Click object { button, type, x, 2 more }` - - `"auto"` + A click action. - - `background: optional "transparent" or "opaque" or "auto"` + - `DoubleClick object { keys, type, x, y }` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + A double click action. - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + - `Drag object { path, type, keys }` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + A drag action. - - `"transparent"` + - `Keypress object { keys, type }` - - `"opaque"` + A collection of keypresses the model would like to perform. - - `"auto"` + - `Move object { type, x, y, keys }` - - `input_fidelity: optional "high" or "low"` + A mouse move 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`. + - `Screenshot object { type }` - - `"high"` + A screenshot action. - - `"low"` + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - - `input_image_mask: optional object { file_id, image_url }` + A scroll action. - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `Type object { text, type }` - - `file_id: optional string` + An action to type in text. - File ID for the mask image. + - `Wait object { type }` - - `image_url: optional string` + A wait action. - Base64-encoded mask image. + - `agent: optional object { agent_name }` - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + 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-2" or 3 more` + - `ComputerCallOutput object { id, call_id, output, 5 more }` - The image generation model to use. Default: `gpt-image-1`. + - `id: string` - - `"gpt-image-1"` + The unique ID of the computer call tool output. - - `"gpt-image-1-mini"` + - `call_id: string` - - `"gpt-image-2"` + The ID of the computer tool call that produced the output. - - `"gpt-image-2-2026-04-21"` + - `output: BetaResponseComputerToolCallOutputScreenshot` - - `"gpt-image-1.5"` + A computer screenshot image used with the computer use tool. - - `"chatgpt-image-latest"` + - `type: "computer_screenshot"` - - `moderation: optional "auto" or "low"` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - Moderation level for the generated image. Default: `auto`. + - `"computer_screenshot"` - - `"auto"` + - `file_id: optional string` - - `"low"` + The identifier of an uploaded file that contains the screenshot. - - `output_compression: optional number` + - `image_url: optional string` - Compression level for the output image. Default: 100. + The URL of the screenshot image. - - `output_format: optional "png" or "webp" or "jpeg"` + - `status: "completed" or "incomplete" or "failed" or "in_progress"` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `"png"` + - `"completed"` - - `"webp"` + - `"incomplete"` - - `"jpeg"` + - `"failed"` - - `partial_images: optional number` + - `"in_progress"` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `type: "computer_call_output"` - - `quality: optional "low" or "medium" or "high" or "auto"` + The type of the computer tool call output. Always `computer_call_output`. - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `"computer_call_output"` - - `"low"` + - `acknowledged_safety_checks: optional array of object { id, code, message }` - - `"medium"` + The safety checks reported by the API that have been acknowledged by the + developer. - - `"high"` + - `id: string` - - `"auto"` + The ID of the pending safety check. - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `code: 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 type of the pending safety check. - - `string` + - `message: optional string` - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + Details about the pending safety check. - 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"` + - `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. + - `Reasoning object { id, summary, type, 4 more }` - - `type: "local_shell"` + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](/docs/guides/conversation-state). - The type of the local shell tool. Always `local_shell`. + - `id: string` - - `"local_shell"` + The unique identifier of the reasoning content. - - `Shell object { type, allowed_callers, environment }` + - `summary: array of object { text, type }` - A tool that allows the model to execute shell commands. + Reasoning summary content. - - `type: "shell"` + - `text: string` - The type of the shell tool. Always `shell`. + A summary of the reasoning output from the model so far. - - `"shell"` + - `type: "summary_text"` - - `allowed_callers: optional array of "direct" or "programmatic"` + The type of the object. Always `summary_text`. - The tool invocation context(s). + - `"summary_text"` - - `"direct"` + - `type: "reasoning"` - - `"programmatic"` + The type of the object. Always `reasoning`. - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + - `"reasoning"` - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `agent: optional object { agent_name }` - - `type: "container_auto"` + The agent that produced this item. - Automatically creates a container for this request + - `agent_name: string` - - `"container_auto"` + The canonical name of the agent that produced this item. - - `file_ids: optional array of string` + - `content: optional array of object { text, type }` - An optional list of uploaded files to make available to your code. + Reasoning text content. - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `text: string` - The memory limit for the container. + The reasoning text from the model. - - `"1g"` + - `type: "reasoning_text"` - - `"4g"` + The type of the reasoning text. Always `reasoning_text`. - - `"16g"` + - `"reasoning_text"` - - `"64g"` + - `encrypted_content: optional string` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - Network access policy for the container. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `BetaContainerNetworkPolicyDisabled object { type }` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `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 }` + - `Compaction object { id, encrypted_content, type, 2 more }` - - `skill_id: string` + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + + - `id: string` - The ID of the referenced skill. + The unique ID of the compaction item. - - `type: "skill_reference"` + - `encrypted_content: string` - References a skill created with the /v1/skills endpoint. + The encrypted content that was produced by compaction. - - `"skill_reference"` + - `type: "compaction"` - - `version: optional string` + The type of the item. Always `compaction`. - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `"compaction"` - - `BetaInlineSkill object { description, name, source, type }` + - `agent: optional object { agent_name }` - - `description: string` + The agent that produced this item. - The description of the skill. + - `agent_name: string` - - `name: string` + The canonical name of the agent that produced this item. - The name of the skill. + - `created_by: optional string` - - `source: BetaInlineSkillSource` + The identifier of the actor that created the item. - Inline skill payload + - `CodeInterpreterCall object { id, code, container_id, 4 more }` - - `data: string` + A tool call to run code. - Base64-encoded skill zip bundle. + - `id: string` - - `media_type: "application/zip"` + The unique ID of the code interpreter tool call. - The media type of the inline skill payload. Must be `application/zip`. + - `code: string` - - `"application/zip"` + The code to run, or null if not available. - - `type: "base64"` + - `container_id: string` - The type of the inline skill source. Must be `base64`. + The ID of the container used to run the code. - - `"base64"` + - `outputs: array of object { logs, type } or object { type, url }` - - `type: "inline"` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - Defines an inline skill for this request. + - `Logs object { logs, type }` - - `"inline"` + The logs output from the code interpreter. - - `BetaLocalEnvironment object { type, skills }` + - `logs: string` - - `type: "local"` + The logs output from the code interpreter. - Use a local computer environment. + - `type: "logs"` - - `"local"` + The type of the output. Always `logs`. - - `skills: optional array of BetaLocalSkill` + - `"logs"` - An optional list of skills. + - `Image object { type, url }` - - `description: string` + The image output from the code interpreter. - The description of the skill. + - `type: "image"` - - `name: string` + The type of the output. Always `image`. - The name of the skill. + - `"image"` - - `path: string` + - `url: string` - The path to the directory containing the skill. + The URL of the image output from the code interpreter. - - `BetaContainerReference object { container_id, type }` + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - - `container_id: string` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - The ID of the referenced container. + - `"in_progress"` - - `type: "container_reference"` + - `"completed"` - References a container created with the /v1/containers endpoint + - `"incomplete"` - - `"container_reference"` + - `"interpreting"` - - `Custom object { name, type, allowed_callers, 3 more }` + - `"failed"` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `type: "code_interpreter_call"` - - `name: string` + The type of the code interpreter tool call. Always `code_interpreter_call`. - The name of the custom tool, used to identify it in tool calls. + - `"code_interpreter_call"` - - `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). + - `LocalShellCall object { id, action, call_id, 3 more }` - - `"direct"` + A tool call to run a command on the local shell. - - `"programmatic"` + - `id: string` - - `defer_loading: optional boolean` + The unique ID of the local shell call. - Whether this tool should be deferred and discovered via tool search. + - `action: object { command, env, type, 3 more }` - - `description: optional string` + Execute a shell command on the server. - Optional description of the custom tool, used to provide more context. + - `command: array of string` - - `format: optional object { type } or object { definition, syntax, type }` + The command to run. - The input format for the custom tool. Default is unconstrained text. + - `env: map[string]` - - `Text object { type }` + Environment variables to set for the command. - Unconstrained free-form text. + - `type: "exec"` - - `type: "text"` + The type of the local shell action. Always `exec`. - Unconstrained text format. Always `text`. + - `"exec"` - - `"text"` + - `timeout_ms: optional number` - - `Grammar object { definition, syntax, type }` + Optional timeout in milliseconds for the command. - A grammar defined by the user. + - `user: optional string` - - `definition: string` + Optional user to run the command as. - The grammar definition. + - `working_directory: optional string` - - `syntax: "lark" or "regex"` + Optional working directory to run the command in. - The syntax of the grammar definition. One of `lark` or `regex`. + - `call_id: string` - - `"lark"` + The unique ID of the local shell tool call generated by the model. - - `"regex"` + - `status: "in_progress" or "completed" or "incomplete"` - - `type: "grammar"` + The status of the local shell call. - Grammar format. Always `grammar`. + - `"in_progress"` - - `"grammar"` + - `"completed"` - - `Namespace object { description, name, tools, type }` + - `"incomplete"` - Groups function/custom tools under a shared namespace. + - `type: "local_shell_call"` - - `description: string` + The type of the local shell call. Always `local_shell_call`. - A description of the namespace shown to the model. + - `"local_shell_call"` - - `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 }` + - `LocalShellCallOutput object { id, output, type, 2 more }` - - `name: string` + The output of a local shell tool call. - - `type: "function"` + - `id: string` - - `"function"` + The unique ID of the local shell tool call generated by the model. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `output: string` - The tool invocation context(s). + A JSON string of the output of the local shell tool call. - - `"direct"` + - `type: "local_shell_call_output"` - - `"programmatic"` + The type of the local shell tool call output. Always `local_shell_call_output`. - - `defer_loading: optional boolean` + - `"local_shell_call_output"` - Whether this function should be deferred and discovered via tool search. + - `agent: optional object { agent_name }` - - `description: optional string` + The agent that produced this item. - - `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` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `strict: optional boolean` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - 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](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `"incomplete"` - - `name: string` + - `ShellCall object { id, action, call_id, 6 more }` - The name of the custom tool, used to identify it in tool calls. + A tool call that executes one or more shell commands in a managed environment. - - `type: "custom"` + - `id: string` - The type of the custom tool. Always `custom`. + The unique ID of the shell tool call. Populated when this item is returned via API. - - `"custom"` + - `action: object { commands, max_output_length, timeout_ms }` - - `allowed_callers: optional array of "direct" or "programmatic"` + The shell commands and limits that describe how to run the tool call. - The tool invocation context(s). + - `commands: array of string` - - `"direct"` + - `max_output_length: number` - - `"programmatic"` + Optional maximum number of characters to return from each command. - - `defer_loading: optional boolean` + - `timeout_ms: number` - Whether this tool should be deferred and discovered via tool search. + Optional timeout in milliseconds for the commands. - - `description: optional string` + - `call_id: string` - Optional description of the custom tool, used to provide more context. + The unique ID of the shell tool call generated by the model. - - `format: optional object { type } or object { definition, syntax, type }` + - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` - The input format for the custom tool. Default is unconstrained text. + Represents the use of a local environment to perform shell actions. - - `Text object { type }` + - `BetaResponseLocalEnvironment object { type }` - Unconstrained free-form text. + Represents the use of a local environment to perform shell actions. - - `type: "text"` + - `type: "local"` - Unconstrained text format. Always `text`. + The environment type. Always `local`. - - `"text"` + - `"local"` - - `Grammar object { definition, syntax, type }` + - `BetaResponseContainerReference object { container_id, type }` - A grammar defined by the user. + Represents a container created with /v1/containers. - - `definition: string` + - `container_id: string` - The grammar definition. + - `type: "container_reference"` - - `syntax: "lark" or "regex"` + The environment type. Always `container_reference`. - The syntax of the grammar definition. One of `lark` or `regex`. + - `"container_reference"` - - `"lark"` + - `status: "in_progress" or "completed" or "incomplete"` - - `"regex"` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `type: "grammar"` + - `"in_progress"` - Grammar format. Always `grammar`. + - `"completed"` - - `"grammar"` + - `"incomplete"` - - `type: "namespace"` + - `type: "shell_call"` - The type of the tool. Always `namespace`. + The type of the item. Always `shell_call`. - - `"namespace"` + - `"shell_call"` - - `ToolSearch object { type, description, execution, parameters }` + - `agent: optional object { agent_name }` - Hosted or BYOT tool search configuration for deferred tools. + The agent that produced this item. - - `type: "tool_search"` + - `agent_name: string` - The type of the tool. Always `tool_search`. + The canonical name of the agent that produced this item. - - `"tool_search"` + - `caller: optional object { type } or object { caller_id, type }` - - `description: optional string` + The execution context that produced this tool call. - Description shown to the model for a client-executed tool search tool. + - `Direct object { type }` - - `execution: optional "server" or "client"` + - `type: "direct"` - Whether tool search is executed by the server or by the client. + - `"direct"` - - `"server"` + - `Program object { caller_id, type }` - - `"client"` + - `caller_id: string` - - `parameters: optional unknown` + The call ID of the program item that produced this tool call. - Parameter schema for a client-executed tool search tool. + - `type: "program"` - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + - `"program"` - 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). + - `created_by: optional string` - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + The ID of the entity that created this tool call. - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `ShellCallOutput object { id, call_id, max_output_length, 6 more }` - - `"web_search_preview"` + The output of a shell tool call that was emitted. - - `"web_search_preview_2025_03_11"` + - `id: string` - - `search_content_types: optional array of "text" or "image"` + The unique ID of the shell call output. Populated when this item is returned via API. - - `"text"` + - `call_id: string` - - `"image"` + The unique ID of the shell tool call generated by the model. - - `search_context_size: optional "low" or "medium" or "high"` + - `max_output_length: 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 maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - `"low"` + - `output: array of object { outcome, stderr, stdout, created_by }` - - `"medium"` + An array of shell call output contents - - `"high"` + - `outcome: object { type } or object { exit_code, type }` - - `user_location: optional object { type, city, country, 2 more }` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - The user's location. + - `Timeout object { type }` - - `type: "approximate"` + Indicates that the shell call exceeded its configured time limit. - The type of location approximation. Always `approximate`. + - `type: "timeout"` - - `"approximate"` + The outcome type. Always `timeout`. - - `city: optional string` + - `"timeout"` - Free text input for the city of the user, e.g. `San Francisco`. + - `Exit object { exit_code, type }` - - `country: optional string` + Indicates that the shell commands finished and returned an exit code. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `exit_code: number` - - `region: optional string` + Exit code from the shell process. - Free text input for the region of the user, e.g. `California`. + - `type: "exit"` - - `timezone: optional string` + The outcome type. Always `exit`. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `"exit"` - - `ApplyPatch object { type, allowed_callers }` + - `stderr: string` - Allows the assistant to create, delete, or update files using unified diffs. + The standard error output that was captured. - - `type: "apply_patch"` + - `stdout: string` - The type of the tool. Always `apply_patch`. + The standard output that was captured. - - `"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). + - `status: "in_progress" or "completed" or "incomplete"` - - `"direct"` + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - `"programmatic"` + - `"in_progress"` - - `type: "tool_search_output"` + - `"completed"` - The item type. Always `tool_search_output`. + - `"incomplete"` - - `"tool_search_output"` + - `type: "shell_call_output"` - - `id: optional string` + The type of the shell call output. Always `shell_call_output`. - The unique ID of this tool search output. + - `"shell_call_output"` - `agent: optional object { agent_name }` @@ -53546,1701 +54631,1678 @@ Cancel a response 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. + - `caller: optional object { type } or object { caller_id, type }` - - `execution: optional "server" or "client"` + The execution context that produced this tool call. - Whether tool search was executed by the server or by the client. + - `Direct object { type }` - - `"server"` + - `type: "direct"` - - `"client"` + - `"direct"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `Program object { caller_id, type }` - The status of the tool search output. + - `caller_id: string` - - `"in_progress"` + The call ID of the program item that produced this tool call. - - `"completed"` + - `type: "program"` - - `"incomplete"` + - `"program"` - - `AdditionalTools object { role, tools, type, 2 more }` + - `created_by: optional string` - - `role: "developer"` + The identifier of the actor that created the item. - The role that provided the additional tools. Only `developer` is supported. + - `ApplyPatchCall object { id, call_id, operation, 5 more }` - - `"developer"` + A tool call that applies file diffs by creating, deleting, or updating files. - - `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` - A list of additional tools made available at this item. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `Function object { name, parameters, strict, 5 more }` + - `call_id: string` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + The unique ID of the apply patch tool call generated by the model. - - `name: string` + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - The name of the function to call. + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `parameters: map[unknown]` + - `CreateFile object { diff, path, type }` - A JSON schema object describing the parameters of the function. + Instruction describing how to create a file via the apply_patch tool. - - `strict: boolean` + - `diff: string` - Whether strict parameter validation is enforced for this function tool. + Diff to apply. - - `type: "function"` + - `path: string` - The type of the function tool. Always `function`. + Path of the file to create. - - `"function"` + - `type: "create_file"` - - `allowed_callers: optional array of "direct" or "programmatic"` + Create a new file with the provided diff. - The tool invocation context(s). + - `"create_file"` - - `"direct"` + - `DeleteFile object { path, type }` - - `"programmatic"` + Instruction describing how to delete a file via the apply_patch tool. - - `defer_loading: optional boolean` + - `path: string` - Whether this function is deferred and loaded via tool search. + Path of the file to delete. - - `description: optional string` + - `type: "delete_file"` - A description of the function. Used by the model to determine whether or not to call the function. + Delete the specified file. - - `output_schema: optional map[unknown]` + - `"delete_file"` - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `UpdateFile object { diff, path, type }` - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + Instruction describing how to update a file via the apply_patch tool. - 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). + - `diff: string` - - `type: "file_search"` + Diff to apply. - The type of the file search tool. Always `file_search`. + - `path: string` - - `"file_search"` + Path of the file to update. - - `vector_store_ids: array of string` + - `type: "update_file"` - The IDs of the vector stores to search. + Update an existing file with the provided diff. - - `filters: optional object { key, type, value } or object { filters, type }` + - `"update_file"` - A filter to apply. + - `status: "in_progress" or "completed"` - - `ComparisonFilter object { key, type, value }` + The status of the apply patch tool call. One of `in_progress` or `completed`. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `"in_progress"` - - `key: string` + - `"completed"` - The key to compare against the value. + - `type: "apply_patch_call"` - - `type: "eq" or "ne" or "gt" or 5 more` + The type of the item. Always `apply_patch_call`. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `"apply_patch_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"` + - `caller: optional object { type } or object { caller_id, type }` - - `"lt"` + The execution context that produced this tool call. - - `"lte"` + - `Direct object { type }` - - `"in"` + - `type: "direct"` - - `"nin"` + - `"direct"` - - `value: string or number or boolean or array of string or number` + - `Program object { caller_id, type }` - The value to compare against the attribute key; supports string, number, or boolean types. + - `caller_id: string` - - `string` + The call ID of the program item that produced this tool call. - - `number` + - `type: "program"` - - `boolean` + - `"program"` - - `array of string or number` + - `created_by: optional string` - - `string` + The ID of the entity that created this tool call. - - `number` + - `ApplyPatchCallOutput object { id, call_id, status, 5 more }` - - `CompoundFilter object { filters, type }` + The output emitted by an apply patch tool call. - Combine multiple filters using `and` or `or`. + - `id: string` - - `filters: array of object { key, type, value } or unknown` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `call_id: string` - - `ComparisonFilter object { key, type, value }` + The unique ID of the apply patch tool call generated by the model. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `status: "completed" or "failed"` - - `key: string` + The status of the apply patch tool call output. One of `completed` or `failed`. - The key to compare against the value. + - `"completed"` - - `type: "eq" or "ne" or "gt" or 5 more` + - `"failed"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `type: "apply_patch_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 + The type of the item. Always `apply_patch_call_output`. - - `"eq"` + - `"apply_patch_call_output"` - - `"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"` + - `caller: optional object { type } or object { caller_id, type }` - - `"in"` + The execution context that produced this tool call. - - `"nin"` + - `Direct object { type }` - - `value: string or number or boolean or array of string or number` + - `type: "direct"` - The value to compare against the attribute key; supports string, number, or boolean types. + - `"direct"` - - `string` + - `Program object { caller_id, type }` - - `number` + - `caller_id: string` - - `boolean` + The call ID of the program item that produced this tool call. - - `array of string or number` + - `type: "program"` - - `string` + - `"program"` - - `number` + - `created_by: optional string` - - `unknown` + The ID of the entity that created this tool call output. - - `type: "and" or "or"` + - `output: optional string` - Type of operation: `and` or `or`. + Optional textual output returned by the apply patch tool. - - `"and"` + - `McpListTools object { id, server_label, tools, 3 more }` - - `"or"` + A list of tools available on an MCP server. - - `max_num_results: optional number` + - `id: string` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + The unique ID of the list. - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `server_label: string` - Ranking options for search. + The label of the MCP server. - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `tools: array of object { input_schema, name, annotations, description }` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + The tools available on the server. - - `embedding_weight: number` + - `input_schema: unknown` - The weight of the embedding in the reciprocal ranking fusion. + The JSON schema describing the tool's input. - - `text_weight: number` + - `name: string` - The weight of the text in the reciprocal ranking fusion. + The name of the tool. - - `ranker: optional "auto" or "default-2024-11-15"` + - `annotations: optional unknown` - The ranker to use for the file search. + Additional annotations about the tool. - - `"auto"` + - `description: optional string` - - `"default-2024-11-15"` + The description of the tool. - - `score_threshold: optional number` + - `type: "mcp_list_tools"` - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + The type of the item. Always `mcp_list_tools`. - - `Computer object { type }` + - `"mcp_list_tools"` - 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 }` - - `type: "computer"` + The agent that produced this item. - The type of the computer tool. Always `computer`. + - `agent_name: string` - - `"computer"` + The canonical name of the agent that produced this item. - - `ComputerUsePreview object { display_height, display_width, environment, type }` + - `error: optional string` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + Error message if the server could not list tools. - - `display_height: number` + - `McpApprovalRequest object { id, arguments, name, 3 more }` - The height of the computer display. + A request for human approval of a tool invocation. - - `display_width: number` + - `id: string` - The width of the computer display. + The unique ID of the approval request. - - `environment: "windows" or "mac" or "linux" or 2 more` + - `arguments: string` - The type of computer environment to control. + A JSON string of arguments for the tool. - - `"windows"` + - `name: string` - - `"mac"` + The name of the tool to run. - - `"linux"` + - `server_label: string` - - `"ubuntu"` + The label of the MCP server making the request. - - `"browser"` + - `type: "mcp_approval_request"` - - `type: "computer_use_preview"` + The type of the item. Always `mcp_approval_request`. - The type of the computer use tool. Always `computer_use_preview`. + - `"mcp_approval_request"` - - `"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](https://platform.openai.com/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`. + - `McpApprovalResponse object { id, approval_request_id, approve, 3 more }` - - `"web_search"` + A response to an MCP approval request. - - `"web_search_2025_08_26"` + - `id: string` - - `filters: optional object { allowed_domains }` + The unique ID of the approval response - Filters for the search. + - `approval_request_id: string` - - `allowed_domains: optional array of string` + The ID of the approval request being answered. - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `approve: boolean` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + Whether the request was approved. - - `search_context_size: optional "low" or "medium" or "high"` + - `type: "mcp_approval_response"` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + The type of the item. Always `mcp_approval_response`. - - `"low"` + - `"mcp_approval_response"` - - `"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` + - `reason: optional string` - Free text input for the city of the user, e.g. `San Francisco`. + Optional reason for the decision. - - `country: optional string` + - `McpCall object { id, arguments, name, 7 more }` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + An invocation of a tool on an MCP server. - - `region: optional string` + - `id: string` - Free text input for the region of the user, e.g. `California`. + The unique ID of the 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 passed to the tool. - - `type: optional "approximate"` + - `name: string` - The type of location approximation. Always `approximate`. + The name of the tool that was run. - - `"approximate"` + - `server_label: string` - - `Mcp object { server_label, type, allowed_callers, 9 more }` + The label of the MCP server running the tool. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `type: "mcp_call"` - - `server_label: string` + The type of the item. Always `mcp_call`. - A label for this MCP server, used to identify it in tool calls. + - `"mcp_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). + - `approval_request_id: optional string` - - `"direct"` + 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. - - `"programmatic"` + - `error: optional string` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + The error from the tool call, if any. - List of allowed tool names or a filter object. + - `output: optional string` - - `McpAllowedTools = array of string` + The output from the tool call. - A string array of allowed tool names + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - - `McpToolFilter object { read_only, tool_names }` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - 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` + - `"calling"` - List of allowed tool names. + - `"failed"` - - `authorization: optional string` + - `CustomToolCall object { call_id, input, name, 5 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. + A call to a custom tool created by the model. - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + - `call_id: string` - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + An identifier used to map this custom tool call to a tool call output. - Currently supported `connector_id` values are: + - `input: string` - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + The input for the custom tool call generated by the model. - - `"connector_dropbox"` + - `name: string` - - `"connector_gmail"` + The name of the custom tool being called. - - `"connector_googlecalendar"` + - `type: "custom_tool_call"` - - `"connector_googledrive"` + The type of the custom tool call. Always `custom_tool_call`. - - `"connector_microsoftteams"` + - `"custom_tool_call"` - - `"connector_outlookcalendar"` + - `id: optional string` - - `"connector_outlookemail"` + The unique ID of the custom tool call in the OpenAI platform. - - `"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. + - `caller: optional object { type } or object { caller_id, type }` - - `require_approval: optional object { always, never } or "always" or "never"` + The execution context that produced this tool call. - Specify which of the MCP server's tools require approval. + - `Direct object { type }` - - `McpToolApprovalFilter object { always, never }` + - `type: "direct"` - 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"` - - `always: 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. + - `namespace: optional string` - - `never: optional object { read_only, tool_names }` + The namespace of the custom tool being called. - A filter object to specify which tools are allowed. + - `CustomToolCallOutput object { call_id, output, type, 3 more }` - - `read_only: optional boolean` + The output of a custom tool call from your code, being sent back 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. + - `call_id: string` - - `tool_names: optional array of string` + The call ID, used to map this custom tool call output to a custom tool call. - List of allowed tool names. + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `McpToolApprovalSetting = "always" or "never"` + The output from the custom tool call generated by your code. + Can be a string or an list of output 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. + - `StringOutput = string` - - `"always"` + A string of the output of the custom tool call. - - `"never"` + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `server_description: optional string` + Text, image, or file output of the custom tool call. - Optional description of the MCP server, used to provide more context. + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `server_url: optional string` + A text input to the model. - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `tunnel_id: optional string` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - 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. + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `CodeInterpreter object { container, type, allowed_callers }` + A file input to the model. - A tool that runs Python code to help generate a response to a prompt. + - `type: "custom_tool_call_output"` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + The type of the custom tool call output. Always `custom_tool_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. + - `"custom_tool_call_output"` - - `string` + - `id: optional string` - The container ID. + The unique ID of the custom tool call output in the OpenAI platform. - - `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"` + - `caller: optional object { type } or object { caller_id, type }` - - `file_ids: optional array of string` + The execution context that produced this tool call. - An optional list of uploaded files to make available to your code. + - `Direct object { type }` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `type: "direct"` - The memory limit for the code interpreter container. + The caller type. Always `direct`. - - `"1g"` + - `"direct"` - - `"4g"` + - `Program object { caller_id, type }` - - `"16g"` + - `caller_id: string` - - `"64g"` + The call ID of the program item that produced this tool call. - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `type: "program"` - Network access policy for the container. + The caller type. Always `program`. - - `BetaContainerNetworkPolicyDisabled object { type }` + - `"program"` - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `usage: BetaResponseUsage` - - `type: "code_interpreter"` + Token accounting for the compaction pass, including cached, reasoning, and total tokens. - The type of the code interpreter tool. Always `code_interpreter`. + - `input_tokens: number` - - `"code_interpreter"` + 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. - - `ProgrammaticToolCalling object { type }` + - `cached_tokens: number` - - `type: "programmatic_tool_calling"` + The number of tokens that were retrieved from the cache. + [More on prompt caching](/docs/guides/prompt-caching). - The type of the tool. Always `programmatic_tool_calling`. + - `output_tokens: number` - - `"programmatic_tool_calling"` + The number of output tokens. - - `ImageGeneration object { type, action, background, 9 more }` + - `output_tokens_details: object { reasoning_tokens }` - A tool that generates images using the GPT image models. + A detailed breakdown of the output tokens. - - `type: "image_generation"` + - `reasoning_tokens: number` - The type of the image generation tool. Always `image_generation`. + The number of reasoning tokens. - - `"image_generation"` + - `total_tokens: number` - - `action: optional "generate" or "edit" or "auto"` + The total number of tokens used. - Whether to generate a new image or edit an existing image. Default: `auto`. +### Beta Computer Action - - `"generate"` +- `BetaComputerAction = object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` - - `"edit"` + A click action. - - `"auto"` + - `Click object { button, type, x, 2 more }` - - `background: optional "transparent" or "opaque" or "auto"` + A click action. - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + - `button: "left" or "right" or "wheel" or 2 more` - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `"left"` - - `"transparent"` + - `"right"` - - `"opaque"` + - `"wheel"` - - `"auto"` + - `"back"` - - `input_fidelity: optional "high" or "low"` + - `"forward"` - 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: "click"` - - `"high"` + Specifies the event type. For a click action, this property is always `click`. - - `"low"` + - `"click"` - - `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 where the click occurred. - - `file_id: optional string` + - `y: number` - File ID for the mask image. + The y-coordinate where the click occurred. - - `image_url: optional string` + - `keys: optional array of string` - Base64-encoded mask image. + The keys being held while clicking. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `DoubleClick object { keys, type, x, y }` - The image generation model to use. Default: `gpt-image-1`. + A double click action. - - `string` + - `keys: array of string` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + The keys being held while double-clicking. - The image generation model to use. Default: `gpt-image-1`. + - `type: "double_click"` - - `"gpt-image-1"` + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `"gpt-image-1-mini"` + - `"double_click"` - - `"gpt-image-2"` + - `x: number` - - `"gpt-image-2-2026-04-21"` + The x-coordinate where the double click occurred. - - `"gpt-image-1.5"` + - `y: number` - - `"chatgpt-image-latest"` + The y-coordinate where the double click occurred. - - `moderation: optional "auto" or "low"` + - `Drag object { path, type, keys }` - Moderation level for the generated image. Default: `auto`. + A drag action. - - `"auto"` + - `path: array of object { x, y }` - - `"low"` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `output_compression: optional number` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - Compression level for the output image. Default: 100. + - `x: number` - - `output_format: optional "png" or "webp" or "jpeg"` + The x-coordinate. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `y: number` - - `"png"` + The y-coordinate. - - `"webp"` + - `type: "drag"` - - `"jpeg"` + Specifies the event type. For a drag action, this property is always set to `drag`. - - `partial_images: optional number` + - `"drag"` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `keys: optional array of string` - - `quality: optional "low" or "medium" or "high" or "auto"` + The keys being held while dragging the mouse. - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `Keypress object { keys, type }` - - `"low"` + A collection of keypresses the model would like to perform. - - `"medium"` + - `keys: array of string` - - `"high"` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `"auto"` + - `type: "keypress"` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `"keypress"` - - `string` + - `Move object { type, x, y, keys }` - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + A mouse move action. - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `type: "move"` - - `"1024x1024"` + Specifies the event type. For a move action, this property is always set to `move`. - - `"1024x1536"` + - `"move"` - - `"1536x1024"` + - `x: number` - - `"auto"` + The x-coordinate to move to. - - `LocalShell object { type }` + - `y: number` - A tool that allows the model to execute shell commands in a local environment. + The y-coordinate to move to. - - `type: "local_shell"` + - `keys: optional array of string` - The type of the local shell tool. Always `local_shell`. + The keys being held while moving the mouse. - - `"local_shell"` + - `Screenshot object { type }` - - `Shell object { type, allowed_callers, environment }` + A screenshot action. - A tool that allows the model to execute shell commands. + - `type: "screenshot"` - - `type: "shell"` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - The type of the shell tool. Always `shell`. + - `"screenshot"` - - `"shell"` + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - - `allowed_callers: optional array of "direct" or "programmatic"` + A scroll action. - The tool invocation context(s). + - `scroll_x: number` - - `"direct"` + The horizontal scroll distance. - - `"programmatic"` + - `scroll_y: number` - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + The vertical scroll distance. - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `type: "scroll"` - - `BetaLocalEnvironment object { type, skills }` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `BetaContainerReference object { container_id, type }` + - `"scroll"` - - `Custom object { name, type, allowed_callers, 3 more }` + - `x: number` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The x-coordinate where the scroll occurred. - - `name: string` + - `y: number` - The name of the custom tool, used to identify it in tool calls. + The y-coordinate where the scroll occurred. - - `type: "custom"` + - `keys: optional array of string` - The type of the custom tool. Always `custom`. + The keys being held while scrolling. - - `"custom"` + - `Type object { text, type }` - - `allowed_callers: optional array of "direct" or "programmatic"` + An action to type in text. - The tool invocation context(s). + - `text: string` - - `"direct"` + The text to type. - - `"programmatic"` + - `type: "type"` - - `defer_loading: optional boolean` + Specifies the event type. For a type action, this property is always set to `type`. - Whether this tool should be deferred and discovered via tool search. + - `"type"` - - `description: optional string` + - `Wait object { type }` - Optional description of the custom tool, used to provide more context. + A wait action. - - `format: optional object { type } or object { definition, syntax, type }` + - `type: "wait"` - The input format for the custom tool. Default is unconstrained text. + Specifies the event type. For a wait action, this property is always set to `wait`. - - `Text object { type }` + - `"wait"` - Unconstrained free-form text. +### Beta Computer Action List - - `type: "text"` +- `BetaComputerActionList = array of BetaComputerAction` - Unconstrained text format. Always `text`. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `"text"` + - `Click object { button, type, x, 2 more }` - - `Grammar object { definition, syntax, type }` + A click action. - A grammar defined by the user. + - `button: "left" or "right" or "wheel" or 2 more` - - `definition: string` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - The grammar definition. + - `"left"` - - `syntax: "lark" or "regex"` + - `"right"` - The syntax of the grammar definition. One of `lark` or `regex`. + - `"wheel"` - - `"lark"` + - `"back"` - - `"regex"` + - `"forward"` - - `type: "grammar"` + - `type: "click"` - Grammar format. Always `grammar`. + Specifies the event type. For a click action, this property is always `click`. - - `"grammar"` + - `"click"` - - `Namespace object { description, name, tools, type }` + - `x: number` - Groups function/custom tools under a shared namespace. + The x-coordinate where the click occurred. - - `description: string` + - `y: number` - A description of the namespace shown to the model. + The y-coordinate where the click occurred. - - `name: string` + - `keys: optional array of string` - The namespace name used in tool calls (for example, `crm`). + The keys being held while clicking. - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + - `DoubleClick object { keys, type, x, y }` - The function/custom tools available inside this namespace. + A double click action. - - `Function object { name, type, allowed_callers, 5 more }` + - `keys: array of string` - - `name: string` + The keys being held while double-clicking. - - `type: "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 should be deferred and discovered via tool search. + - `Drag object { path, type, keys }` - - `description: optional string` + A drag action. - - `output_schema: optional map[unknown]` + - `path: array of object { x, y }` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `parameters: optional unknown` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `strict: optional boolean` + - `x: 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 x-coordinate. - - `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](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The y-coordinate. - - `name: string` + - `type: "drag"` - The name of the custom tool, used to identify it in tool calls. + Specifies the event type. For a drag action, this property is always set to `drag`. - - `type: "custom"` + - `"drag"` - The type of the custom tool. Always `custom`. + - `keys: optional array of string` - - `"custom"` + The keys being held while dragging the mouse. - - `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"` + - `keys: array of string` - - `"programmatic"` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `defer_loading: optional boolean` + - `type: "keypress"` - Whether this tool should be deferred and discovered via tool search. + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `description: optional string` + - `"keypress"` - Optional description of the custom tool, used to provide more context. + - `Move object { type, x, y, keys }` - - `format: optional object { type } or object { definition, syntax, type }` + A mouse move action. - The input format for the custom tool. Default is unconstrained text. + - `type: "move"` - - `Text object { type }` + Specifies the event type. For a move action, this property is always set to `move`. - Unconstrained free-form text. + - `"move"` - - `type: "text"` + - `x: number` - Unconstrained text format. Always `text`. + The x-coordinate to move to. - - `"text"` + - `y: number` - - `Grammar object { definition, syntax, type }` + The y-coordinate to move to. - A grammar defined by the user. + - `keys: optional array of string` - - `definition: string` + The keys being held while moving the mouse. - The grammar definition. + - `Screenshot object { type }` - - `syntax: "lark" or "regex"` + A screenshot action. - The syntax of the grammar definition. One of `lark` or `regex`. + - `type: "screenshot"` - - `"lark"` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `"regex"` + - `"screenshot"` - - `type: "grammar"` + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - Grammar format. Always `grammar`. + A scroll action. - - `"grammar"` + - `scroll_x: number` - - `type: "namespace"` + The horizontal scroll distance. - The type of the tool. Always `namespace`. + - `scroll_y: number` - - `"namespace"` + The vertical scroll distance. - - `ToolSearch object { type, description, execution, parameters }` + - `type: "scroll"` - Hosted or BYOT tool search configuration for deferred tools. + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `type: "tool_search"` + - `"scroll"` - The type of the tool. Always `tool_search`. + - `x: number` - - `"tool_search"` + The x-coordinate where the scroll occurred. - - `description: optional string` + - `y: number` - Description shown to the model for a client-executed tool search tool. + The y-coordinate where the scroll occurred. - - `execution: optional "server" or "client"` + - `keys: optional array of string` - Whether tool search is executed by the server or by the client. + The keys being held while scrolling. - - `"server"` + - `Type object { text, type }` - - `"client"` + An action to type in text. - - `parameters: optional unknown` + - `text: string` - Parameter schema for a client-executed tool search tool. + The text to type. - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + - `type: "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). + Specifies the event type. For a type action, this property is always set to `type`. - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `"type"` - 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"` + - `type: "wait"` - - `search_content_types: optional array of "text" or "image"` + Specifies the event type. For a wait action, this property is always set to `wait`. - - `"text"` + - `"wait"` - - `"image"` +### Beta Container Auto - - `search_context_size: optional "low" or "medium" or "high"` +- `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `type: "container_auto"` - - `"low"` + Automatically creates a container for this request - - `"medium"` + - `"container_auto"` - - `"high"` + - `file_ids: optional array of string` - - `user_location: optional object { type, city, country, 2 more }` + An optional list of uploaded files to make available to your code. - The user's location. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `type: "approximate"` + The memory limit for the container. - The type of location approximation. Always `approximate`. + - `"1g"` - - `"approximate"` + - `"4g"` - - `city: optional string` + - `"16g"` - Free text input for the city of the user, e.g. `San Francisco`. + - `"64g"` - - `country: optional string` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + Network access policy for the container. - - `region: optional string` + - `BetaContainerNetworkPolicyDisabled object { type }` - Free text input for the region of the user, e.g. `California`. + - `type: "disabled"` - - `timezone: optional string` + Disable outbound network access. Always `disabled`. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `"disabled"` - - `ApplyPatch object { type, allowed_callers }` + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - Allows the assistant to create, delete, or update files using unified diffs. + - `allowed_domains: array of string` - - `type: "apply_patch"` + A list of allowed domains when type is `allowlist`. - The type of the tool. Always `apply_patch`. + - `type: "allowlist"` - - `"apply_patch"` + Allow outbound network access only to specified domains. Always `allowlist`. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"allowlist"` - The tool invocation context(s). + - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` - - `"direct"` + Optional domain-scoped secrets for allowlisted domains. - - `"programmatic"` + - `domain: string` - - `type: "additional_tools"` + The domain associated with the secret. - The item type. Always `additional_tools`. + - `name: string` - - `"additional_tools"` + The name of the secret to inject for the domain. - - `id: optional string` + - `value: string` - The unique ID of this additional tools item. + The secret value to inject for the domain. - - `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` - - `Reasoning object { id, summary, type, 4 more }` + The ID of the referenced skill. - 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](https://platform.openai.com/docs/guides/conversation-state). + - `type: "skill_reference"` - - `id: string` + References a skill created with the /v1/skills endpoint. - The unique identifier of the reasoning content. + - `"skill_reference"` - - `summary: array of object { text, type }` + - `version: optional string` - Reasoning summary content. + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `text: string` + - `BetaInlineSkill object { description, name, source, type }` - A summary of the reasoning output from the model so far. + - `description: string` - - `type: "summary_text"` + The description of the skill. - The type of the object. Always `summary_text`. + - `name: string` - - `"summary_text"` + The name of the skill. - - `type: "reasoning"` + - `source: BetaInlineSkillSource` - The type of the object. Always `reasoning`. + Inline skill payload - - `"reasoning"` + - `data: string` - - `agent: optional object { agent_name }` + Base64-encoded skill zip bundle. - The agent that produced this item. + - `media_type: "application/zip"` - - `agent_name: string` + The media type of the inline skill payload. Must be `application/zip`. - The canonical name of the agent that produced this item. + - `"application/zip"` - - `content: optional array of object { text, type }` + - `type: "base64"` - Reasoning text content. + The type of the inline skill source. Must be `base64`. - - `text: string` + - `"base64"` - The reasoning text from the model. + - `type: "inline"` - - `type: "reasoning_text"` + Defines an inline skill for this request. - The type of the reasoning text. Always `reasoning_text`. + - `"inline"` - - `"reasoning_text"` +### Beta Container Network Policy Allowlist - - `encrypted_content: optional string` +- `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `allowed_domains: array of string` - - `status: optional "in_progress" or "completed" or "incomplete"` + A list of allowed domains when type is `allowlist`. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `type: "allowlist"` - - `"in_progress"` + Allow outbound network access only to specified domains. Always `allowlist`. - - `"completed"` + - `"allowlist"` - - `"incomplete"` + - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` - - `Compaction object { encrypted_content, type, id, agent }` + Optional domain-scoped secrets for allowlisted domains. - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `domain: string` - - `encrypted_content: string` + The domain associated with the secret. - The encrypted content of the compaction summary. + - `name: string` - - `type: "compaction"` + The name of the secret to inject for the domain. - The type of the item. Always `compaction`. + - `value: string` - - `"compaction"` + The secret value to inject for the domain. - - `id: optional string` +### Beta Container Network Policy Disabled - The ID of the compaction item. +- `BetaContainerNetworkPolicyDisabled object { type }` - - `agent: optional object { agent_name }` + - `type: "disabled"` - The agent that produced this item. + Disable outbound network access. Always `disabled`. - - `agent_name: string` + - `"disabled"` - The canonical name of the agent that produced this item. +### Beta Container Network Policy Domain Secret - - `ImageGenerationCall object { id, result, status, 2 more }` +- `BetaContainerNetworkPolicyDomainSecret object { domain, name, value }` - An image generation request made by the model. + - `domain: string` - - `id: string` + The domain associated with the secret. - The unique ID of the image generation call. + - `name: string` - - `result: string` + The name of the secret to inject for the domain. - The generated image encoded in base64. + - `value: string` - - `status: "in_progress" or "completed" or "generating" or "failed"` + The secret value to inject for the domain. - The status of the image generation call. +### Beta Container Reference - - `"in_progress"` +- `BetaContainerReference object { container_id, type }` - - `"completed"` + - `container_id: string` - - `"generating"` + The ID of the referenced container. - - `"failed"` + - `type: "container_reference"` - - `type: "image_generation_call"` + References a container created with the /v1/containers endpoint - The type of the image generation call. Always `image_generation_call`. + - `"container_reference"` - - `"image_generation_call"` +### Beta Easy Input Message - - `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. - - `CodeInterpreterCall object { id, code, container_id, 4 more }` + - `TextInput = string` - A tool call to run code. + A text input to the model. - - `id: string` + - `BetaResponseInputMessageContentList = array of BetaResponseInputContent` - The unique ID of the code interpreter tool call. + A list of one or many input items to the model, containing different content + types. - - `code: string` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - The code to run, or null if not available. + A text input to the model. - - `container_id: string` + - `text: string` - The ID of the container used to run the code. + The text input to the model. - - `outputs: array of object { logs, type } or object { type, url }` + - `type: "input_text"` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + The type of the input item. Always `input_text`. - - `Logs object { logs, type }` + - `"input_text"` - The logs output from the code interpreter. + - `prompt_cache_breakpoint: optional object { mode }` - - `logs: 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 logs output from the code interpreter. + - `mode: "explicit"` - - `type: "logs"` + The breakpoint mode. Always `explicit`. - The type of the output. Always `logs`. + - `"explicit"` - - `"logs"` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `Image object { type, url }` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - The image output from the code interpreter. + - `detail: "low" or "high" or "auto" or "original"` - - `type: "image"` + 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 output. Always `image`. + - `"low"` - - `"image"` + - `"high"` - - `url: string` + - `"auto"` - The URL of the image output from the code interpreter. + - `"original"` - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + - `type: "input_image"` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + The type of the input item. Always `input_image`. - - `"in_progress"` + - `"input_image"` - - `"completed"` + - `file_id: optional string` - - `"incomplete"` + The ID of the file to be sent to the model. - - `"interpreting"` + - `image_url: optional string` - - `"failed"` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `type: "code_interpreter_call"` + - `prompt_cache_breakpoint: optional object { mode }` - The type of the code interpreter tool call. Always `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. - - `"code_interpreter_call"` + - `mode: "explicit"` - - `agent: optional object { agent_name }` + The breakpoint mode. Always `explicit`. - The agent that produced this item. + - `"explicit"` - - `agent_name: string` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - The canonical name of the agent that produced this item. + A file input to the model. - - `LocalShellCall object { id, action, call_id, 3 more }` + - `type: "input_file"` - A tool call to run a command on the local shell. + The type of the input item. Always `input_file`. - - `id: string` + - `"input_file"` - The unique ID of the local shell call. + - `detail: optional "auto" or "low" or "high"` - - `action: object { command, env, type, 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`. - Execute a shell command on the server. + - `"auto"` - - `command: array of string` + - `"low"` - The command to run. + - `"high"` - - `env: map[string]` + - `file_data: optional string` - Environment variables to set for the command. + The content of the file to be sent to the model. - - `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"` + - `file_url: optional string` - - `timeout_ms: optional number` + The URL of the file to be sent to the model. - Optional timeout in milliseconds for the command. + - `filename: optional string` - - `user: optional string` + The name of the file to be sent to the model. - Optional user to run the command as. + - `prompt_cache_breakpoint: optional object { mode }` - - `working_directory: 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 working directory to run the command in. + - `mode: "explicit"` - - `call_id: string` + The breakpoint mode. Always `explicit`. - The unique ID of the local shell tool call generated by the model. + - `"explicit"` - - `status: "in_progress" or "completed" or "incomplete"` + - `role: "user" or "assistant" or "system" or "developer"` - The status of the local shell call. + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - - `"in_progress"` + - `"user"` - - `"completed"` + - `"assistant"` - - `"incomplete"` + - `"system"` - - `type: "local_shell_call"` + - `"developer"` - The type of the local shell call. Always `local_shell_call`. + - `phase: optional "commentary" or "final_answer"` - - `"local_shell_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. - - `agent: optional object { agent_name }` + - `"commentary"` - The agent that produced this item. + - `"final_answer"` - - `agent_name: string` + - `type: optional "message"` - The canonical name of the agent that produced this item. + The type of the message input. Always `message`. - - `LocalShellCallOutput object { id, output, type, 2 more }` + - `"message"` - The output of a local shell tool call. +### Beta Inline Skill - - `id: string` +- `BetaInlineSkill object { description, name, source, type }` - The unique ID of the local shell tool call generated by the model. + - `description: string` - - `output: string` + The description of the skill. - A JSON string of the output of the local shell tool call. + - `name: string` - - `type: "local_shell_call_output"` + The name of the skill. - The type of the local shell tool call output. Always `local_shell_call_output`. + - `source: BetaInlineSkillSource` - - `"local_shell_call_output"` + Inline skill payload - - `agent: optional object { agent_name }` + - `data: string` - The agent that produced this item. + Base64-encoded skill zip bundle. - - `agent_name: string` + - `media_type: "application/zip"` - The canonical name of the agent that produced this item. + The media type of the inline skill payload. Must be `application/zip`. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"application/zip"` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `type: "base64"` - - `"in_progress"` + The type of the inline skill source. Must be `base64`. - - `"completed"` + - `"base64"` - - `"incomplete"` + - `type: "inline"` - - `ShellCall object { action, call_id, type, 5 more }` + Defines an inline skill for this request. - A tool representing a request to execute one or more shell commands. + - `"inline"` - - `action: object { commands, max_output_length, timeout_ms }` +### Beta Inline Skill Source - The shell commands and limits that describe how to run the tool call. +- `BetaInlineSkillSource object { data, media_type, type }` - - `commands: array of string` + Inline skill payload - Ordered shell commands for the execution environment to run. + - `data: string` - - `max_output_length: optional number` + Base64-encoded skill zip bundle. - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + - `media_type: "application/zip"` - - `timeout_ms: optional number` + The media type of the inline skill payload. Must be `application/zip`. - Maximum wall-clock time in milliseconds to allow the shell commands to run. + - `"application/zip"` - - `call_id: string` + - `type: "base64"` - The unique ID of the shell tool call generated by the model. + The type of the inline skill source. Must be `base64`. - - `type: "shell_call"` + - `"base64"` - The type of the item. Always `shell_call`. +### Beta Local Environment - - `"shell_call"` +- `BetaLocalEnvironment object { type, skills }` - - `id: optional string` + - `type: "local"` - The unique ID of the shell tool call. Populated when this item is returned via API. + Use a local computer environment. - - `agent: optional object { agent_name }` + - `"local"` - The agent that produced this item. + - `skills: optional array of BetaLocalSkill` - - `agent_name: string` + An optional list of skills. - The canonical name of the agent that produced this item. + - `description: string` - - `caller: optional object { type } or object { caller_id, type }` + The description of the skill. - The execution context that produced this tool call. + - `name: string` - - `Direct object { type }` + The name of the skill. - - `type: "direct"` + - `path: string` - The caller type. Always `direct`. + The path to the directory containing the skill. - - `"direct"` +### Beta Local Skill - - `Program object { caller_id, type }` +- `BetaLocalSkill object { description, name, path }` - - `caller_id: string` + - `description: string` - The call ID of the program item that produced this tool call. + The description of the skill. - - `type: "program"` + - `name: string` - The caller type. Always `program`. + The name of the skill. - - `"program"` + - `path: string` - - `environment: optional BetaLocalEnvironment or BetaContainerReference` + The path to the directory containing the skill. - The environment to execute the shell commands in. +### Beta Response - - `BetaLocalEnvironment object { type, skills }` +- `BetaResponse object { id, created_at, error, 32 more }` - - `BetaContainerReference object { container_id, type }` + - `id: string` - - `status: optional "in_progress" or "completed" or "incomplete"` + Unique identifier for this Response. - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `created_at: number` - - `"in_progress"` + Unix timestamp (in seconds) of when this Response was created. - - `"completed"` + - `error: BetaResponseError` - - `"incomplete"` + An error object returned when the model fails to generate a Response. - - `ShellCallOutput object { call_id, output, type, 5 more }` + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 16 more` - The streamed output items emitted by a shell tool call. + The error code for the response. - - `call_id: string` + - `"server_error"` - The unique ID of the shell tool call generated by the model. + - `"rate_limit_exceeded"` - - `output: array of BetaResponseFunctionShellCallOutputContent` + - `"invalid_prompt"` - Captured chunks of stdout and stderr output, along with their associated outcomes. + - `"bio_policy"` - - `outcome: object { type } or object { exit_code, type }` + - `"vector_store_timeout"` - The exit or timeout outcome associated with this shell call. + - `"invalid_image"` - - `Timeout object { type }` + - `"invalid_image_format"` - Indicates that the shell call exceeded its configured time limit. + - `"invalid_base64_image"` - - `type: "timeout"` + - `"invalid_image_url"` - The outcome type. Always `timeout`. + - `"image_too_large"` - - `"timeout"` + - `"image_too_small"` - - `Exit object { exit_code, type }` + - `"image_parse_error"` - Indicates that the shell commands finished and returned an exit code. + - `"image_content_policy_violation"` - - `exit_code: number` + - `"invalid_image_mode"` - The exit code returned by the shell process. + - `"image_file_too_large"` - - `type: "exit"` + - `"unsupported_image_media_type"` - The outcome type. Always `exit`. + - `"empty_image_file"` - - `"exit"` + - `"failed_to_download_image"` - - `stderr: string` + - `"image_file_not_found"` - Captured stderr output for the shell call. + - `message: string` - - `stdout: string` + A human-readable description of the error. - Captured stdout output for the shell call. + - `incomplete_details: object { reason }` - - `type: "shell_call_output"` + Details about why the response is incomplete. - The type of the item. Always `shell_call_output`. + - `reason: optional "max_output_tokens" or "content_filter"` - - `"shell_call_output"` + The reason why the response is incomplete. - - `id: optional string` + - `"max_output_tokens"` - The unique ID of the shell tool call output. Populated when this item is returned via API. + - `"content_filter"` - - `agent: optional object { agent_name }` + - `instructions: string or array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` - The agent that produced this item. + A system (or developer) message inserted into the model's context. - - `agent_name: 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 canonical name of the agent that produced this item. + - `string` - - `caller: optional object { type } or object { caller_id, type }` + A text input to the model, equivalent to a text input with the + `developer` role. - The execution context that produced this tool call. + - `InputItemList = array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` - - `Direct object { type }` + A list of one or many input items to the model, containing + different content types. - - `type: "direct"` + - `BetaEasyInputMessage object { content, role, phase, type }` - The caller type. Always `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. - - `"direct"` + - `content: string or BetaResponseInputMessageContentList` - - `Program object { caller_id, type }` + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `caller_id: string` + - `TextInput = string` - The call ID of the program item that produced this tool call. + A text input to the model. - - `type: "program"` + - `BetaResponseInputMessageContentList = array of BetaResponseInputContent` - The caller type. Always `program`. + A list of one or many input items to the model, containing different content + types. - - `"program"` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `max_output_length: optional number` + A text input to the model. - The maximum number of UTF-8 characters captured for this shell call's combined output. + - `text: string` - - `status: optional "in_progress" or "completed" or "incomplete"` + The text input to the model. - The status of the shell call output. + - `type: "input_text"` - - `"in_progress"` + The type of the input item. Always `input_text`. - - `"completed"` + - `"input_text"` - - `"incomplete"` + - `prompt_cache_breakpoint: optional object { mode }` - - `ApplyPatchCall object { call_id, operation, status, 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 tool call representing a request to create, delete, or update files using diff patches. + - `mode: "explicit"` - - `call_id: string` + The breakpoint mode. Always `explicit`. - The unique ID of the apply patch tool call generated by the model. + - `"explicit"` - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - The specific create, delete, or update instruction for the apply_patch tool call. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `CreateFile object { diff, path, type }` + - `detail: "low" or "high" or "auto" or "original"` - Instruction for creating a new file via the apply_patch tool. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `diff: string` + - `"low"` - Unified diff content to apply when creating the file. + - `"high"` - - `path: string` + - `"auto"` - Path of the file to create relative to the workspace root. + - `"original"` - - `type: "create_file"` + - `type: "input_image"` - The operation type. Always `create_file`. + The type of the input item. Always `input_image`. - - `"create_file"` + - `"input_image"` - - `DeleteFile object { path, type }` + - `file_id: optional string` - Instruction for deleting an existing file via the apply_patch tool. + The ID of the file to be sent to the model. - - `path: string` + - `image_url: optional string` - Path of the file to delete relative to the workspace root. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `type: "delete_file"` + - `prompt_cache_breakpoint: optional object { mode }` - The operation type. Always `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. - - `"delete_file"` + - `mode: "explicit"` - - `UpdateFile object { diff, path, type }` + The breakpoint mode. Always `explicit`. - Instruction for updating an existing file via the apply_patch tool. + - `"explicit"` - - `diff: string` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - Unified diff content to apply to the existing file. + A file input to the model. - - `path: string` + - `type: "input_file"` - Path of the file to update relative to the workspace root. + The type of the input item. Always `input_file`. - - `type: "update_file"` + - `"input_file"` - The operation type. Always `update_file`. + - `detail: optional "auto" or "low" or "high"` - - `"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`. - - `status: "in_progress" or "completed"` + - `"auto"` - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `"low"` - - `"in_progress"` + - `"high"` - - `"completed"` + - `file_data: optional string` - - `type: "apply_patch_call"` + The content of the file to be sent to the model. - The type of the item. Always `apply_patch_call`. + - `file_id: optional string` - - `"apply_patch_call"` + The ID of the file to be sent to the model. - - `id: optional string` + - `file_url: optional string` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + 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. - - `caller: optional object { type } or object { caller_id, type }` + - `mode: "explicit"` - The execution context that produced this tool call. + The breakpoint mode. Always `explicit`. - - `Direct object { type }` + - `"explicit"` - - `type: "direct"` + - `role: "user" or "assistant" or "system" or "developer"` - The caller type. Always `direct`. + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - - `"direct"` + - `"user"` - - `Program object { caller_id, type }` + - `"assistant"` - - `caller_id: string` + - `"system"` - The call ID of the program item that produced this tool call. + - `"developer"` - - `type: "program"` + - `phase: optional "commentary" or "final_answer"` - The caller type. Always `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. - - `"program"` + - `"commentary"` - - `ApplyPatchCallOutput object { call_id, status, type, 4 more }` + - `"final_answer"` - The streamed output emitted by an apply patch tool call. + - `type: optional "message"` - - `call_id: string` + The type of the message input. Always `message`. - The unique ID of the apply patch tool call generated by the model. + - `"message"` - - `status: "completed" or "failed"` + - `Message object { content, role, agent, 2 more }` - The status of the apply patch tool call output. One of `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. - - `"completed"` + - `content: BetaResponseInputMessageContentList` - - `"failed"` + A list of one or many input items to the model, containing different content + types. - - `type: "apply_patch_call_output"` + - `role: "user" or "system" or "developer"` - The type of the item. Always `apply_patch_call_output`. + The role of the message input. One of `user`, `system`, or `developer`. - - `"apply_patch_call_output"` + - `"user"` - - `id: optional string` + - `"system"` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `"developer"` - `agent: optional object { agent_name }` @@ -55250,202 +56312,189 @@ Cancel a response 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 }` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `caller_id: string` + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The call ID of the program item that produced this tool call. + - `"in_progress"` - - `type: "program"` + - `"completed"` - The caller type. Always `program`. + - `"incomplete"` - - `"program"` + - `type: optional "message"` - - `output: optional string` + The type of the message input. Always set to `message`. - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + - `"message"` - - `McpListTools object { id, server_label, tools, 3 more }` + - `BetaResponseOutputMessage object { id, content, role, 4 more }` - A list of tools available on an MCP server. + An output message from the model. - `id: string` - The unique ID of the list. - - - `server_label: string` + The unique ID of the output message. - The label of the MCP server. + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - - `tools: array of object { input_schema, name, annotations, description }` + The content of the output message. - The tools available on the server. + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - - `input_schema: unknown` + A text output from the model. - The JSON schema describing the tool's input. + - `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 }` - - `name: string` + The annotations of the text output. - The name of the tool. + - `FileCitation object { file_id, filename, index, type }` - - `annotations: optional unknown` + A citation to a file. - Additional annotations about the tool. + - `file_id: string` - - `description: optional string` + The ID of the file. - The description of the tool. + - `filename: string` - - `type: "mcp_list_tools"` + The filename of the file cited. - The type of the item. Always `mcp_list_tools`. + - `index: number` - - `"mcp_list_tools"` + The index of the file in the list of files. - - `agent: optional object { agent_name }` + - `type: "file_citation"` - The agent that produced this item. + The type of the file citation. Always `file_citation`. - - `agent_name: string` + - `"file_citation"` - The canonical name of the agent that produced this item. + - `URLCitation object { end_index, start_index, title, 2 more }` - - `error: optional string` + A citation for a web resource used to generate a model response. - Error message if the server could not list tools. + - `end_index: number` - - `McpApprovalRequest object { id, arguments, name, 3 more }` + The index of the last character of the URL citation in the message. - A request for human approval of a tool invocation. + - `start_index: number` - - `id: string` + The index of the first character of the URL citation in the message. - The unique ID of the approval request. + - `title: string` - - `arguments: string` + The title of the web resource. - A JSON string of arguments for the tool. + - `type: "url_citation"` - - `name: string` + The type of the URL citation. Always `url_citation`. - The name of the tool to run. + - `"url_citation"` - - `server_label: string` + - `url: string` - The label of the MCP server making the request. + The URL of the web resource. - - `type: "mcp_approval_request"` + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - The type of the item. Always `mcp_approval_request`. + A citation for a container file used to generate a model response. - - `"mcp_approval_request"` + - `container_id: string` - - `agent: optional object { agent_name }` + The ID of the container file. - The agent that produced this item. + - `end_index: number` - - `agent_name: string` + The index of the last character of the container file citation in the message. - The canonical name of the agent that produced this item. + - `file_id: string` - - `McpApprovalResponse object { approval_request_id, approve, type, 3 more }` + The ID of the file. - A response to an MCP approval request. + - `filename: string` - - `approval_request_id: string` + The filename of the container file cited. - The ID of the approval request being answered. + - `start_index: number` - - `approve: boolean` + The index of the first character of the container file citation in the message. - Whether the request was approved. + - `type: "container_file_citation"` - - `type: "mcp_approval_response"` + The type of the container file citation. Always `container_file_citation`. - The type of the item. Always `mcp_approval_response`. + - `"container_file_citation"` - - `"mcp_approval_response"` + - `FilePath object { file_id, index, type }` - - `id: optional string` + A path to a file. - The unique ID of the approval response + - `file_id: string` - - `agent: optional object { agent_name }` + The ID of the file. - 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_path"` - - `reason: optional string` + The type of the file path. Always `file_path`. - Optional reason for the decision. + - `"file_path"` - - `McpCall object { id, arguments, name, 7 more }` + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - An invocation of a tool on an MCP server. + - `token: string` - - `id: string` + - `bytes: array of number` - The unique ID of the tool call. + - `logprob: number` - - `arguments: string` + - `top_logprobs: array of object { token, bytes, logprob }` - A JSON string of the arguments passed to the tool. + - `token: string` - - `name: string` + - `bytes: array of number` - The name of the tool that was run. + - `logprob: number` - - `server_label: string` + - `text: string` - The label of the MCP server running the tool. + The text output from the model. - - `type: "mcp_call"` + - `type: "output_text"` - The type of the item. Always `mcp_call`. + The type of the output text. Always `output_text`. - - `"mcp_call"` + - `"output_text"` - - `agent: optional object { agent_name }` + - `BetaResponseOutputRefusal object { refusal, type }` - The agent that produced this item. + A refusal from the model. - - `agent_name: string` + - `refusal: string` - The canonical name of the agent that produced this item. + The refusal explanation from the model. - - `approval_request_id: optional string` + - `type: "refusal"` - 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 refusal. Always `refusal`. - - `error: optional string` + - `"refusal"` - The error from the tool call, if any. + - `role: "assistant"` - - `output: optional string` + The role of the output message. Always `assistant`. - The output from the tool call. + - `"assistant"` - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `status: "in_progress" or "completed" or "incomplete"` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - `"in_progress"` @@ -55453,52 +56502,63 @@ Cancel a response - `"incomplete"` - - `"calling"` + - `type: "message"` - - `"failed"` + The type of the output message. Always `message`. - - `CustomToolCallOutput object { call_id, output, type, 3 more }` + - `"message"` - The output of a custom tool call from your code, being sent back to the model. + - `agent: optional object { agent_name }` - - `call_id: string` + The agent that produced this item. - The call ID, used to map this custom tool call output to a custom tool call. + - `agent_name: string` - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + The canonical name of the agent that produced this item. - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `phase: optional "commentary" or "final_answer"` - - `StringOutput = 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. - A string of the output of the custom tool call. + - `"commentary"` - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `"final_answer"` - Text, image, or file output of the custom tool call. + - `FileSearchCall object { id, queries, status, 3 more }` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + The results of a file search tool call. See the + [file search guide](/docs/guides/tools-file-search) for more information. - A text input to 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](https://platform.openai.com/docs/guides/vision). + - `queries: array of string` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + The queries used to search for files. - A file input to the model. + - `status: "in_progress" or "searching" or "completed" or 2 more` - - `type: "custom_tool_call_output"` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - The type of the custom tool call output. Always `custom_tool_call_output`. + - `"in_progress"` - - `"custom_tool_call_output"` + - `"searching"` - - `id: optional string` + - `"completed"` - The unique ID of the custom tool call output in the OpenAI platform. + - `"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 }` @@ -55508,512 +56568,509 @@ Cancel a response 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. - The caller type. Always `direct`. + - `string` - - `"direct"` + - `number` - - `Program object { caller_id, type }` + - `boolean` - - `caller_id: string` + - `file_id: optional string` - The call ID of the program item that produced this tool call. + The unique ID of the file. - - `type: "program"` + - `filename: optional string` - The caller type. Always `program`. + The name of the file. - - `"program"` + - `score: optional number` - - `CustomToolCall object { call_id, input, name, 5 more }` + The relevance score of the file - a value between 0 and 1. - A call to a custom tool created by the model. + - `text: optional string` - - `call_id: string` + The text that was retrieved from the file. - An identifier used to map this custom tool call to a tool call output. + - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` - - `input: string` + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - The input for the custom tool call generated by the model. + - `id: string` - - `name: string` + The unique ID of the computer call. - The name of the custom tool being called. + - `call_id: string` - - `type: "custom_tool_call"` + An identifier used when responding to the tool call with output. - The type of the custom tool call. Always `custom_tool_call`. + - `pending_safety_checks: array of object { id, code, message }` - - `"custom_tool_call"` + The pending safety checks for the computer call. - - `id: optional string` + - `id: string` - The unique ID of the custom tool call in the OpenAI platform. + The ID of the pending safety check. - - `agent: optional object { agent_name }` + - `code: optional string` - The agent that produced this item. + The type of the pending safety check. - - `agent_name: string` + - `message: optional string` - The canonical name of the agent that produced this item. + Details about the pending safety check. - - `caller: optional object { type } or object { caller_id, type }` + - `status: "in_progress" or "completed" or "incomplete"` - The execution context that produced this tool call. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `Direct object { type }` + - `"in_progress"` - - `type: "direct"` + - `"completed"` - - `"direct"` + - `"incomplete"` - - `Program object { caller_id, type }` + - `type: "computer_call"` - - `caller_id: string` + The type of the computer call. Always `computer_call`. - The call ID of the program item that produced this tool call. + - `"computer_call"` - - `type: "program"` + - `action: optional BetaComputerAction` - - `"program"` + A click action. - - `namespace: optional string` + - `Click object { button, type, x, 2 more }` - The namespace of the custom tool being called. + A click action. - - `CompactionTrigger object { type, agent }` + - `button: "left" or "right" or "wheel" or 2 more` - Compacts the current context. Must be the final input item. + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `type: "compaction_trigger"` + - `"left"` - The type of the item. Always `compaction_trigger`. + - `"right"` - - `"compaction_trigger"` + - `"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`. - - `ItemReference object { id, agent, type }` + - `"click"` - An internal identifier for an item to reference. + - `x: number` - - `id: string` + The x-coordinate where the click occurred. - The ID of the item to reference. + - `y: number` - - `agent: optional object { agent_name }` + The y-coordinate where the click occurred. - The agent that produced this item. + - `keys: optional array of string` - - `agent_name: string` + The keys being held while clicking. - The canonical name of the agent that produced this item. + - `DoubleClick object { keys, type, x, y }` - - `type: optional "item_reference"` + A double click action. - The type of item to reference. Always `item_reference`. + - `keys: array of string` - - `"item_reference"` + The keys being held while double-clicking. - - `Program object { id, call_id, code, 3 more }` + - `type: "double_click"` - - `id: string` + Specifies the event type. For a double click action, this property is always set to `double_click`. - The unique ID of this program item. + - `"double_click"` - - `call_id: string` + - `x: number` - The stable call ID of the program item. + The x-coordinate where the double click occurred. - - `code: string` + - `y: number` - The JavaScript source executed by programmatic tool calling. + The y-coordinate where the double click occurred. - - `fingerprint: string` + - `Drag object { path, type, keys }` - Opaque program replay fingerprint that must be round-tripped. + A drag action. - - `type: "program"` + - `path: array of object { x, y }` - The item type. Always `program`. + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `"program"` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `agent: optional object { agent_name }` + - `x: number` - The agent that produced this item. + The x-coordinate. - - `agent_name: string` + - `y: number` - The canonical name of the agent that produced this item. + The y-coordinate. - - `ProgramOutput object { id, call_id, result, 3 more }` + - `type: "drag"` - - `id: string` + Specifies the event type. For a drag action, this property is always set to `drag`. - The unique ID of this program output item. + - `"drag"` - - `call_id: string` + - `keys: optional array of string` - The call ID of the program item. + The keys being held while dragging the mouse. - - `result: string` + - `Keypress object { keys, type }` - The result produced by the program item. + A collection of keypresses the model would like to perform. - - `status: "completed" or "incomplete"` + - `keys: array of string` - The terminal status of the program output. + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `"completed"` + - `type: "keypress"` - - `"incomplete"` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `type: "program_output"` + - `"keypress"` - The item type. Always `program_output`. + - `Move object { type, x, y, keys }` - - `"program_output"` + A mouse move action. - - `agent: optional object { agent_name }` + - `type: "move"` - The agent that produced this item. + Specifies the event type. For a move action, this property is always set to `move`. - - `agent_name: string` + - `"move"` - The canonical name of the agent that produced this item. + - `x: number` - - `metadata: map[string]` + The x-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. + - `y: number` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The y-coordinate to move to. - - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` + - `keys: optional array of 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](https://platform.openai.com/docs/models) - to browse and compare available models. + The keys being held while moving the mouse. - - `"gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more` + - `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](https://platform.openai.com/docs/models) - to browse and compare available models. + A screenshot action. - - `"gpt-5.6-sol"` + - `type: "screenshot"` - - `"gpt-5.6-terra"` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `"gpt-5.6-luna"` + - `"screenshot"` - - `"gpt-5.4"` + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - - `"gpt-5.4-mini"` + A scroll action. - - `"gpt-5.4-nano"` + - `scroll_x: number` - - `"gpt-5.4-mini-2026-03-17"` + The horizontal scroll distance. - - `"gpt-5.4-nano-2026-03-17"` + - `scroll_y: number` - - `"gpt-5.3-chat-latest"` + The vertical scroll distance. - - `"gpt-5.2"` + - `type: "scroll"` - - `"gpt-5.2-2025-12-11"` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `"gpt-5.2-chat-latest"` + - `"scroll"` - - `"gpt-5.2-pro"` + - `x: number` - - `"gpt-5.2-pro-2025-12-11"` + The x-coordinate where the scroll occurred. - - `"gpt-5.1"` + - `y: number` - - `"gpt-5.1-2025-11-13"` + The y-coordinate where the scroll occurred. - - `"gpt-5.1-codex"` + - `keys: optional array of string` - - `"gpt-5.1-mini"` + The keys being held while scrolling. - - `"gpt-5.1-chat-latest"` + - `Type object { text, type }` - - `"gpt-5"` + An action to type in text. - - `"gpt-5-mini"` + - `text: string` - - `"gpt-5-nano"` + The text to type. - - `"gpt-5-2025-08-07"` + - `type: "type"` - - `"gpt-5-mini-2025-08-07"` + Specifies the event type. For a type action, this property is always set to `type`. - - `"gpt-5-nano-2025-08-07"` + - `"type"` - - `"gpt-5-chat-latest"` + - `Wait object { type }` - - `"gpt-4.1"` + A wait action. - - `"gpt-4.1-mini"` + - `type: "wait"` - - `"gpt-4.1-nano"` + Specifies the event type. For a wait action, this property is always set to `wait`. - - `"gpt-4.1-2025-04-14"` + - `"wait"` - - `"gpt-4.1-mini-2025-04-14"` + - `actions: optional BetaComputerActionList` - - `"gpt-4.1-nano-2025-04-14"` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `"o4-mini"` + - `Click object { button, type, x, 2 more }` - - `"o4-mini-2025-04-16"` + A click action. - - `"o3"` + - `DoubleClick object { keys, type, x, y }` - - `"o3-2025-04-16"` + A double click action. - - `"o3-mini"` + - `Drag object { path, type, keys }` - - `"o3-mini-2025-01-31"` + A drag action. - - `"o1"` + - `Keypress object { keys, type }` - - `"o1-2024-12-17"` + A collection of keypresses the model would like to perform. - - `"o1-preview"` + - `Move object { type, x, y, keys }` - - `"o1-preview-2024-09-12"` + A mouse move action. - - `"o1-mini"` + - `Screenshot object { type }` - - `"o1-mini-2024-09-12"` + A screenshot action. - - `"gpt-4o"` + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - - `"gpt-4o-2024-11-20"` + A scroll action. - - `"gpt-4o-2024-08-06"` + - `Type object { text, type }` - - `"gpt-4o-2024-05-13"` + An action to type in text. - - `"gpt-4o-audio-preview"` + - `Wait object { type }` - - `"gpt-4o-audio-preview-2024-10-01"` + A wait action. - - `"gpt-4o-audio-preview-2024-12-17"` + - `agent: optional object { agent_name }` - - `"gpt-4o-audio-preview-2025-06-03"` + The agent that produced this item. - - `"gpt-4o-mini-audio-preview"` + - `agent_name: string` - - `"gpt-4o-mini-audio-preview-2024-12-17"` + The canonical name of the agent that produced this item. - - `"gpt-4o-search-preview"` + - `ComputerCallOutput object { call_id, output, type, 4 more }` - - `"gpt-4o-mini-search-preview"` + The output of a computer tool call. - - `"gpt-4o-search-preview-2025-03-11"` + - `call_id: string` - - `"gpt-4o-mini-search-preview-2025-03-11"` + The ID of the computer tool call that produced the output. - - `"chatgpt-4o-latest"` + - `output: BetaResponseComputerToolCallOutputScreenshot` - - `"codex-mini-latest"` + A computer screenshot image used with the computer use tool. - - `"gpt-4o-mini"` + - `type: "computer_screenshot"` - - `"gpt-4o-mini-2024-07-18"` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `"gpt-4-turbo"` + - `"computer_screenshot"` - - `"gpt-4-turbo-2024-04-09"` + - `file_id: optional string` - - `"gpt-4-0125-preview"` + The identifier of an uploaded file that contains the screenshot. - - `"gpt-4-turbo-preview"` + - `image_url: optional string` - - `"gpt-4-1106-preview"` + The URL of the screenshot image. - - `"gpt-4-vision-preview"` + - `type: "computer_call_output"` - - `"gpt-4"` + The type of the computer tool call output. Always `computer_call_output`. - - `"gpt-4-0314"` + - `"computer_call_output"` - - `"gpt-4-0613"` + - `id: optional string` - - `"gpt-4-32k"` + The ID of the computer tool call output. - - `"gpt-4-32k-0314"` + - `acknowledged_safety_checks: optional array of object { id, code, message }` - - `"gpt-4-32k-0613"` + The safety checks reported by the API that have been acknowledged by the developer. - - `"gpt-3.5-turbo"` + - `id: string` - - `"gpt-3.5-turbo-16k"` + The ID of the pending safety check. - - `"gpt-3.5-turbo-0301"` + - `code: optional string` - - `"gpt-3.5-turbo-0613"` + The type of the pending safety check. - - `"gpt-3.5-turbo-1106"` + - `message: optional string` - - `"gpt-3.5-turbo-0125"` + Details about the pending safety check. - - `"gpt-3.5-turbo-16k-0613"` + - `agent: optional object { agent_name }` - - `"o1-pro"` + The agent that produced this item. - - `"o1-pro-2025-03-19"` + - `agent_name: string` - - `"o3-pro"` + The canonical name of the agent that produced this item. - - `"o3-pro-2025-06-10"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"o3-deep-research"` + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - - `"o3-deep-research-2025-06-26"` + - `"in_progress"` - - `"o4-mini-deep-research"` + - `"completed"` - - `"o4-mini-deep-research-2025-06-26"` + - `"incomplete"` - - `"computer-use-preview"` + - `WebSearchCall object { id, action, status, 2 more }` - - `"computer-use-preview-2025-03-11"` + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. - - `"gpt-5-codex"` + - `id: string` - - `"gpt-5-pro"` + The unique ID of the web search tool call. - - `"gpt-5-pro-2025-10-06"` + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - - `"gpt-5.1-codex-max"` + 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). - - `string` + - `Search object { type, queries, query, sources }` - - `object: "response"` + Action type "search" - Performs a web search query. - The object type of this resource - always set to `response`. + - `type: "search"` - - `"response"` + The action type. - - `output: array of BetaResponseOutputItem` + - `"search"` - An array of content items generated by the model. + - `queries: optional array of 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 queries. - - `BetaResponseOutputMessage object { id, content, role, 4 more }` + - `query: optional string` - An output message from the model. + The search query. - - `FileSearchCall object { id, queries, status, 3 more }` + - `sources: optional array of object { type, url }` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + The sources used in the search. - - `id: string` + - `type: "url"` - The unique ID of the file search tool call. + The type of source. Always `url`. - - `queries: array of string` + - `"url"` - The queries used to search for files. + - `url: string` - - `status: "in_progress" or "searching" or "completed" or 2 more` + The URL of the source. - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `OpenPage object { type, url }` - - `"in_progress"` + Action type "open_page" - Opens a specific URL from search results. - - `"searching"` + - `type: "open_page"` - - `"completed"` + The action type. - - `"incomplete"` + - `"open_page"` - - `"failed"` + - `url: optional string` - - `type: "file_search_call"` + The URL opened by the model. - The type of the file search tool call. Always `file_search_call`. + - `FindInPage object { pattern, type, url }` - - `"file_search_call"` + Action type "find_in_page": Searches for a pattern within a loaded page. - - `agent: optional object { agent_name }` + - `pattern: string` - The agent that produced this item. + The pattern or text to search for within the page. - - `agent_name: string` + - `type: "find_in_page"` - The canonical name of the agent that produced this item. + The action type. - - `results: optional array of object { attributes, file_id, filename, 2 more }` + - `"find_in_page"` - The results of the file search tool call. + - `url: string` - - `attributes: optional map[string or number or boolean]` + The URL of the page searched for the pattern. - 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. + - `status: "in_progress" or "searching" or "completed" or "failed"` - - `string` + The status of the web search tool call. - - `number` + - `"in_progress"` - - `boolean` + - `"searching"` - - `file_id: optional string` + - `"completed"` - The unique ID of the file. + - `"failed"` - - `filename: optional string` + - `type: "web_search_call"` - The name of the file. + The type of the web search tool call. Always `web_search_call`. - - `score: optional number` + - `"web_search_call"` - The relevance score of the file - a value between 0 and 1. + - `agent: optional object { agent_name }` - - `text: optional string` + The agent that produced this item. - The text that was retrieved from the file. + - `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](https://platform.openai.com/docs/guides/function-calling) for more information. + [function calling guide](/docs/guides/function-calling) for more information. - `arguments: string` @@ -56080,205 +57137,207 @@ Cancel a response - `"incomplete"` - - `FunctionCallOutput object { id, call_id, output, 5 more }` - - - `id: string` + - `FunctionCallOutput object { call_id, output, type, 4 more }` - The unique ID of the function call tool output. + 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` + - `output: string or array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` - The output from the function 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 function 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 function 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 }` + - `text: string` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The text input to the model. - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `type: "input_text"` - A file input to the model. + The type of the input item. Always `input_text`. - - `status: "in_progress" or "completed" or "incomplete"` + - `"input_text"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `prompt_cache_breakpoint: optional object { mode }` - - `"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. - - `"completed"` + - `mode: "explicit"` - - `"incomplete"` + The breakpoint mode. Always `explicit`. - - `type: "function_call_output"` + - `"explicit"` - The type of the function tool call output. Always `function_call_output`. + - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` - - `"function_call_output"` + An image input to the model. Learn about [image inputs](/docs/guides/vision) - - `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. + - `detail: optional "low" or "high" or "auto" or "original"` - - `caller: optional object { type } or 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`. - The execution context that produced this tool call. + - `"low"` - - `Direct object { type }` + - `"high"` - - `type: "direct"` + - `"auto"` - The caller type. Always `direct`. + - `"original"` - - `"direct"` + - `file_id: optional string` - - `Program object { caller_id, type }` + The ID of the file to be sent to the model. - - `caller_id: string` + - `image_url: optional string` - The call ID of the program item that produced this 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. - - `type: "program"` + - `prompt_cache_breakpoint: optional object { mode }` - The caller type. Always `program`. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `"program"` + - `mode: "explicit"` - - `created_by: optional string` + The breakpoint mode. Always `explicit`. - The identifier of the actor that created the item. + - `"explicit"` - - `AgentMessage object { id, author, content, 3 more }` + - `BetaResponseInputFileContent object { type, detail, file_data, 4 more }` - - `id: string` + A file input to the model. - The unique ID of the agent message. + - `type: "input_file"` - - `author: string` + The type of the input item. Always `input_file`. - The sending agent identity. + - `"input_file"` - - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` + - `detail: optional "auto" or "low" or "high"` - Encrypted content sent between agents. + 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`. - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `"auto"` - A text input to the model. + - `"low"` - - `BetaResponseOutputText object { annotations, text, type, logprobs }` + - `"high"` - A text output from the model. + - `file_data: optional string` - - `Text object { text, type }` + The base64-encoded data of the file to be sent to the model. - A text content. + - `file_id: optional string` - - `text: string` + The ID of the file to be sent to the model. - - `type: "text"` + - `file_url: optional string` - - `"text"` + The URL of the file to be sent to the model. - - `SummaryText object { text, type }` + - `filename: optional string` - A summary text from the model. + The name of the file to be sent to the model. - - `text: string` + - `prompt_cache_breakpoint: optional object { mode }` - A summary of the reasoning output from the model so far. + Marks the exact end of a reusable 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: "summary_text"` + - `mode: "explicit"` - The type of the object. Always `summary_text`. + The breakpoint mode. Always `explicit`. - - `"summary_text"` + - `"explicit"` - - `ReasoningText object { text, type }` + - `type: "function_call_output"` - Reasoning text from the model. + The type of the function tool call output. Always `function_call_output`. - - `text: string` + - `"function_call_output"` - The reasoning text from the model. + - `id: optional string` - - `type: "reasoning_text"` + The unique ID of the function tool call output. Populated when this item is returned via API. - 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 }` + - `caller: optional object { type } or object { caller_id, type }` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The execution context that produced this tool call. - - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` + - `Direct object { type }` - A screenshot of a computer. + - `type: "direct"` - - `detail: "low" or "high" or "auto" or "original"` + The caller type. Always `direct`. - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `"direct"` - - `"low"` + - `Program object { caller_id, type }` - - `"high"` + - `caller_id: string` - - `"auto"` + The call ID of the program item that produced this tool call. - - `"original"` + - `type: "program"` - - `file_id: string` + The caller type. Always `program`. - The identifier of an uploaded file that contains the screenshot. + - `"program"` - - `image_url: string` + - `status: optional "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. - - `type: "computer_screenshot"` + - `"in_progress"` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + - `"completed"` - - `"computer_screenshot"` + - `"incomplete"` - - `prompt_cache_breakpoint: optional object { mode }` + - `AgentMessage object { author, content, recipient, 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 message routed between agents. - - `mode: "explicit"` + - `author: string` - The breakpoint mode. Always `explicit`. + The sending agent identity. - - `"explicit"` + - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + Plaintext, image, or encrypted content sent between agents. - A file input to the model. + - `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 }` @@ -56300,10 +57359,14 @@ Cancel a response - `type: "agent_message"` - The type of the item. Always `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. @@ -56312,15 +57375,11 @@ Cancel a response 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. + - `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"` @@ -56336,7 +57395,7 @@ Cancel a response - `arguments: string` - The JSON string of arguments generated for the action. + The action arguments as a JSON string. - `call_id: string` @@ -56344,10 +57403,14 @@ Cancel a response - `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. @@ -56356,11 +57419,7 @@ Cancel a response 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` @@ -56382,395 +57441,105 @@ Cancel a response 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 }` - - The annotations of the text output. - - `text: string` - The text output from the model. + The text content. - `type: "output_text"` - The type of the output text. Always `output_text`. - - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` - - - `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 }` - - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/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. + The content type. Always `output_text`. - - `query: optional string` + - `"output_text"` - The search query. + - `annotations: optional array of object { file_id, filename, index, type } or array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` - - `sources: optional array of object { type, url }` + Citations associated with the text content. - The sources used in the search. + - `array of object { file_id, filename, index, type }` - - `type: "url"` + - `file_id: string` - The type of source. Always `url`. + The ID of the file. - - `"url"` + - `filename: string` - - `url: string` + The filename of the file cited. - The URL of the source. + - `index: number` - - `OpenPage object { type, url }` + The index of the file in the list of files. - Action type "open_page" - Opens a specific URL from search results. + - `type: "file_citation"` - - `type: "open_page"` + The citation type. Always `file_citation`. - The action type. + - `"file_citation"` - - `"open_page"` + - `array of object { end_index, start_index, title, 2 more }` - - `url: optional string` + - `end_index: number` - The URL opened by the model. + The index of the last character of the citation in the message. - - `FindInPage object { pattern, type, url }` + - `start_index: number` - Action type "find_in_page": Searches for a pattern within a loaded page. + The index of the first character of the citation in the message. - - `pattern: string` + - `title: string` - The pattern or text to search for within the page. + The title of the cited resource. - - `type: "find_in_page"` + - `type: "url_citation"` - The action type. + The citation type. Always `url_citation`. - - `"find_in_page"` + - `"url_citation"` - `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. - - - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` - - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/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. - - - `actions: optional BetaComputerActionList` - - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. - - - `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. - - - `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](https://platform.openai.com/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 - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. - - - `status: optional "in_progress" or "completed" or "incomplete"` - - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `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`. + The URL of the cited resource. - - `"program"` + - `array of 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 }` @@ -56780,44 +57549,22 @@ Cancel a response 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. @@ -56826,21 +57573,11 @@ Cancel a response 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. @@ -56848,9 +57585,9 @@ Cancel a response - `"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"` @@ -56858,9 +57595,11 @@ Cancel a response - `"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 }` @@ -57123,7 +57862,7 @@ Cancel a response - `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](https://platform.openai.com/docs/guides/tools-web-search). + [web search tool](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -57183,7 +57922,7 @@ Cancel a response - `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](https://platform.openai.com/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -57235,7 +57974,7 @@ Cancel a response 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -57381,8 +58120,40 @@ Cancel a response - `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`. @@ -57427,19 +58198,8 @@ Cancel a response - `background: optional "transparent" or "opaque" or "auto"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. - - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. - - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - `"transparent"` @@ -57468,13 +58228,13 @@ Cancel a response Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `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-2" or 3 more` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` The image generation model to use. Default: `gpt-image-1`. @@ -57482,14 +58242,8 @@ Cancel a response - `"gpt-image-1-mini"` - - `"gpt-image-2"` - - - `"gpt-image-2-2026-04-21"` - - `"gpt-image-1.5"` - - `"chatgpt-image-latest"` - - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -57580,13 +58334,131 @@ Cancel a response - `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](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -57700,7 +58572,7 @@ Cancel a response - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -57870,10 +58742,14 @@ Cancel a response - `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. @@ -57882,39 +58758,39 @@ Cancel a response 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 }` @@ -58177,7 +59053,7 @@ Cancel a response - `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](https://platform.openai.com/docs/guides/tools-web-search). + [web search tool](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -58237,7 +59113,7 @@ Cancel a response - `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](https://platform.openai.com/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -58289,7 +59165,7 @@ Cancel a response 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -58481,19 +59357,8 @@ Cancel a response - `background: optional "transparent" or "opaque" or "auto"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. - - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. - - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - `"transparent"` @@ -58522,13 +59387,13 @@ Cancel a response Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `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-2" or 3 more` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` The image generation model to use. Default: `gpt-image-1`. @@ -58536,14 +59401,8 @@ Cancel a response - `"gpt-image-1-mini"` - - `"gpt-image-2"` - - - `"gpt-image-2-2026-04-21"` - - `"gpt-image-1.5"` - - `"chatgpt-image-latest"` - - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -58640,7 +59499,7 @@ Cancel a response - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -58754,7 +59613,7 @@ Cancel a response - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -58924,10 +59783,14 @@ Cancel a response - `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. @@ -58936,17 +59799,82 @@ Cancel a response 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](https://platform.openai.com/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 - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `Compaction object { encrypted_content, type, id, 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"` @@ -58954,6 +59882,10 @@ Cancel a response - `"compaction"` + - `id: optional string` + + The ID of the compaction item. + - `agent: optional object { agent_name }` The agent that produced this item. @@ -58962,10 +59894,6 @@ Cancel a response 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. @@ -59183,13 +60111,9 @@ Cancel a response - `"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 }` @@ -59197,60 +60121,30 @@ Cancel a response - `commands: array of string` - - `max_output_length: number` + Ordered shell commands for the execution environment to run. - Optional maximum number of characters to return from each command. + - `max_output_length: optional number` - - `timeout_ms: number` + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - Optional timeout in milliseconds for the commands. + - `timeout_ms: optional number` + + Maximum wall-clock time in milliseconds to allow the shell commands to run. - `call_id: string` The unique ID of the shell tool call generated by the model. - - `environment: 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. @@ -59267,6 +60161,8 @@ Cancel a response - `type: "direct"` + The caller type. Always `direct`. + - `"direct"` - `Program object { caller_id, type }` @@ -59277,35 +60173,43 @@ Cancel a response - `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 }` @@ -59323,7 +60227,7 @@ Cancel a response - `exit_code: number` - Exit code from the shell process. + The exit code returned by the shell process. - `type: "exit"` @@ -59333,32 +60237,22 @@ Cancel a response - `stderr: string` - The standard error output that was captured. + Captured stderr output for the shell call. - `stdout: string` - The standard output that was captured. - - - `created_by: optional string` - - The identifier of the actor that created the item. - - - `status: "in_progress" or "completed" or "incomplete"` - - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` + Captured stdout output for the shell call. - `type: "shell_call_output"` - The type of the shell call output. Always `shell_call_output`. + The type of the item. Always `shell_call_output`. - `"shell_call_output"` + - `id: optional string` + + The unique ID of the shell tool call output. Populated when this item is returned via API. + - `agent: optional object { agent_name }` The agent that produced this item. @@ -59375,6 +60269,8 @@ Cancel a response - `type: "direct"` + The caller type. Always `direct`. + - `"direct"` - `Program object { caller_id, type }` @@ -59385,19 +60281,27 @@ Cancel a response - `type: "program"` + The caller type. Always `program`. + - `"program"` - - `created_by: optional string` + - `max_output_length: optional number` - The identifier of the actor that created the item. + The maximum number of UTF-8 characters captured for this shell call's combined output. - - `ApplyPatchCall object { id, call_id, operation, 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` @@ -59405,55 +60309,55 @@ Cancel a response - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + The specific create, delete, or update instruction for the apply_patch tool call. - `CreateFile object { diff, path, type }` - Instruction describing how to create a file via the apply_patch tool. + Instruction for creating a new file via the apply_patch tool. - `diff: string` - Diff to apply. + Unified diff content to apply when creating the file. - `path: string` - Path of the file to create. + Path of the file to create relative to the workspace root. - `type: "create_file"` - Create a new file with the provided diff. + The operation type. Always `create_file`. - `"create_file"` - `DeleteFile object { path, type }` - Instruction describing how to delete a file via the apply_patch tool. + Instruction for deleting an existing file via the apply_patch tool. - `path: string` - Path of the file to delete. + Path of the file to delete relative to the workspace root. - `type: "delete_file"` - Delete the specified file. + The operation type. Always `delete_file`. - `"delete_file"` - `UpdateFile object { diff, path, type }` - Instruction describing how to update a file via the apply_patch tool. + Instruction for updating an existing file via the apply_patch tool. - `diff: string` - Diff to apply. + Unified diff content to apply to the existing file. - `path: string` - Path of the file to update. + Path of the file to update relative to the workspace root. - `type: "update_file"` - Update an existing file with the provided diff. + The operation type. Always `update_file`. - `"update_file"` @@ -59471,63 +60375,9 @@ Cancel a response - `"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`. + - `id: optional string` - - `"apply_patch_call_output"` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - `agent: optional object { agent_name }` @@ -59545,6 +60395,8 @@ Cancel a response - `type: "direct"` + The caller type. Always `direct`. + - `"direct"` - `Program object { caller_id, type }` @@ -59553,43 +60405,37 @@ Cancel a response 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. + - `type: "program"` - - `output: optional string` + The caller type. Always `program`. - Optional textual output returned by the apply patch tool. + - `"program"` - - `McpCall object { id, arguments, name, 7 more }` + - `ApplyPatchCallOutput object { call_id, status, type, 4 more }` - An invocation of a tool on an MCP server. + The streamed output emitted by an apply patch tool call. - - `id: string` + - `call_id: string` - The unique ID of the tool call. + The unique ID of the apply patch tool call generated by the model. - - `arguments: string` + - `status: "completed" or "failed"` - A JSON string of the arguments passed to the tool. + The status of the apply patch tool call output. One of `completed` or `failed`. - - `name: string` + - `"completed"` - The name of the tool that was run. + - `"failed"` - - `server_label: string` + - `type: "apply_patch_call_output"` - The label of the MCP server running the tool. + The type of the item. Always `apply_patch_call_output`. - - `type: "mcp_call"` + - `"apply_patch_call_output"` - The type of the item. Always `mcp_call`. + - `id: optional string` - - `"mcp_call"` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - `agent: optional object { agent_name }` @@ -59599,32 +60445,33 @@ Cancel a response 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` + The caller type. Always `direct`. - The output from the tool call. + - `"direct"` - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `Program object { caller_id, type }` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `caller_id: string` - - `"in_progress"` + The call ID of the program item that produced this tool call. - - `"completed"` + - `type: "program"` - - `"incomplete"` + The caller type. Always `program`. - - `"calling"` + - `"program"` - - `"failed"` + - `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 }` @@ -59710,14 +60557,10 @@ Cancel a response 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. @@ -59732,6 +60575,10 @@ Cancel a 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. @@ -59744,31 +60591,31 @@ Cancel a response Optional reason for the decision. - - `CustomToolCall object { call_id, input, name, 5 more }` + - `McpCall object { id, arguments, name, 7 more }` - A call to a custom tool created by the model. + An invocation of a tool on an MCP server. - - `call_id: string` + - `id: string` - An identifier used to map this custom tool call to a tool call output. + The unique ID of the tool call. - - `input: string` + - `arguments: string` - The input for the custom tool call generated by the model. + A JSON string of the arguments passed to the tool. - `name: string` - The name of the custom tool being called. + The name of the tool that was run. - - `type: "custom_tool_call"` + - `server_label: string` - The type of the custom tool call. Always `custom_tool_call`. + The label of the MCP server running the tool. - - `"custom_tool_call"` + - `type: "mcp_call"` - - `id: optional string` + The type of the item. Always `mcp_call`. - The unique ID of the custom tool call in the OpenAI platform. + - `"mcp_call"` - `agent: optional object { agent_name }` @@ -59778,35 +60625,36 @@ Cancel a response The canonical name of the agent that produced this item. - - `caller: optional object { type } or object { caller_id, type }` + - `approval_request_id: optional string` - The execution context that produced this tool call. + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - - `Direct object { type }` + - `error: optional string` - - `type: "direct"` + The error from the tool call, if any. - - `"direct"` + - `output: optional string` - - `Program object { caller_id, type }` + The output from the tool call. - - `caller_id: string` + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - The call ID of the program item that produced this tool call. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `type: "program"` + - `"in_progress"` - - `"program"` + - `"completed"` - - `namespace: optional string` + - `"incomplete"` - The namespace of the custom tool being called. + - `"calling"` - - `CustomToolCallOutput object { id, call_id, output, 5 more }` + - `"failed"` - - `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` @@ -59831,29 +60679,22 @@ Cancel a response - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + 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"` + - `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. @@ -59886,3707 +60727,3353 @@ Cancel a response - `"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](https://platform.openai.com/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](https://platform.openai.com/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`. + - `CustomToolCall object { call_id, input, name, 5 more }` - - `"mcp"` + A call to a custom tool created by the model. - - `name: optional string` + - `call_id: string` - The name of the tool to call on the server. + An identifier used to map this custom tool call to a tool call output. - - `BetaToolChoiceCustom object { name, type }` + - `input: string` - Use this option to force the model to call a specific custom tool. + The input for the custom tool call generated by the model. - `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. + The name of the custom tool being called. - - `type: "apply_patch"` + - `type: "custom_tool_call"` - The tool to call. Always `apply_patch`. + The type of the custom tool call. Always `custom_tool_call`. - - `"apply_patch"` + - `"custom_tool_call"` - - `BetaToolChoiceShell object { type }` + - `id: optional string` - Forces the model to call the shell tool when a tool call is required. + The unique ID of the custom tool call in the OpenAI platform. - - `type: "shell"` + - `agent: optional object { agent_name }` - The tool to call. Always `shell`. + The agent that produced this item. - - `"shell"` + - `agent_name: 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 canonical name of 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. + - `caller: optional object { type } or object { caller_id, type }` - We support the following categories of tools: + The execution context that produced this tool call. - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/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](https://platform.openai.com/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](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. + - `Direct object { type }` - - `Function object { name, parameters, strict, 5 more }` + - `type: "direct"` - 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). + - `"direct"` - - `name: string` + - `Program object { caller_id, type }` - The name of the function to call. + - `caller_id: string` - - `parameters: map[unknown]` + The call ID of the program item that produced this tool call. - A JSON schema object describing the parameters of the function. + - `type: "program"` - - `strict: boolean` + - `"program"` - Whether strict parameter validation is enforced for this function tool. + - `namespace: optional string` - - `type: "function"` + The namespace of the custom tool being called. - The type of the function tool. Always `function`. + - `CompactionTrigger object { type, agent }` - - `"function"` + Compacts the current context. Must be the final input item. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `type: "compaction_trigger"` - The tool invocation context(s). + The type of the item. Always `compaction_trigger`. - - `"direct"` + - `"compaction_trigger"` - - `"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. + - `ItemReference object { id, agent, type }` - - `output_schema: optional map[unknown]` + An internal identifier for an item to reference. - 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 ID of the item to reference. - 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: optional object { agent_name }` - - `type: "file_search"` + The agent that produced this item. - The type of the file search tool. Always `file_search`. + - `agent_name: string` - - `"file_search"` + The canonical name of the agent that produced this item. - - `vector_store_ids: array of string` + - `type: optional "item_reference"` - The IDs of the vector stores to search. + The type of item to reference. Always `item_reference`. - - `filters: optional object { key, type, value } or object { filters, type }` + - `"item_reference"` - A filter to apply. + - `Program object { id, call_id, code, 3 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. + The unique ID of this program item. - - `key: string` + - `call_id: string` - The key to compare against the value. + The stable call ID of the program item. - - `type: "eq" or "ne" or "gt" or 5 more` + - `code: string` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The JavaScript source executed by programmatic tool calling. - - `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 + - `fingerprint: string` - - `"eq"` + Opaque program replay fingerprint that must be round-tripped. - - `"ne"` + - `type: "program"` - - `"gt"` + The item type. Always `program`. - - `"gte"` + - `"program"` - - `"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` + - `ProgramOutput object { id, call_id, result, 3 more }` - The value to compare against the attribute key; supports string, number, or boolean types. + - `id: string` - - `string` + The unique ID of this program output item. - - `number` + - `call_id: string` - - `boolean` + The call ID of the program item. - - `array of string or number` + - `result: string` - - `string` + The result produced by the program item. - - `number` + - `status: "completed" or "incomplete"` - - `CompoundFilter object { filters, type }` + The terminal status of the program output. - 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`. + - `type: "program_output"` - - `ComparisonFilter object { key, type, value }` + The item type. Always `program_output`. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `"program_output"` - - `key: string` + - `agent: optional object { agent_name }` - The key to compare against the value. + The agent that produced this item. - - `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 + - `metadata: map[string]` - - `"eq"` + 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. - - `"ne"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `"gt"` + - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` - - `"gte"` + 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. - - `"lt"` + - `"gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more` - - `"lte"` + 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. - - `"in"` + - `"gpt-5.6-sol"` - - `"nin"` + - `"gpt-5.6-terra"` - - `value: string or number or boolean or array of string or number` + - `"gpt-5.6-luna"` - The value to compare against the attribute key; supports string, number, or boolean types. + - `"gpt-5.4"` - - `string` + - `"gpt-5.4-mini"` - - `number` + - `"gpt-5.4-nano"` - - `boolean` + - `"gpt-5.4-mini-2026-03-17"` - - `array of string or number` + - `"gpt-5.4-nano-2026-03-17"` - - `string` + - `"gpt-5.3-chat-latest"` - - `number` + - `"gpt-5.2"` - - `unknown` + - `"gpt-5.2-2025-12-11"` - - `type: "and" or "or"` + - `"gpt-5.2-chat-latest"` - Type of operation: `and` or `or`. + - `"gpt-5.2-pro"` - - `"and"` + - `"gpt-5.2-pro-2025-12-11"` - - `"or"` + - `"gpt-5.1"` - - `max_num_results: optional number` + - `"gpt-5.1-2025-11-13"` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `"gpt-5.1-codex"` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `"gpt-5.1-mini"` - Ranking options for search. + - `"gpt-5.1-chat-latest"` - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `"gpt-5"` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `"gpt-5-mini"` - - `embedding_weight: number` + - `"gpt-5-nano"` - The weight of the embedding in the reciprocal ranking fusion. + - `"gpt-5-2025-08-07"` - - `text_weight: number` + - `"gpt-5-mini-2025-08-07"` - The weight of the text in the reciprocal ranking fusion. + - `"gpt-5-nano-2025-08-07"` - - `ranker: optional "auto" or "default-2024-11-15"` + - `"gpt-5-chat-latest"` - The ranker to use for the file search. + - `"gpt-4.1"` - - `"auto"` + - `"gpt-4.1-mini"` - - `"default-2024-11-15"` + - `"gpt-4.1-nano"` - - `score_threshold: optional number` + - `"gpt-4.1-2025-04-14"` - 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.1-mini-2025-04-14"` - - `Computer object { type }` + - `"gpt-4.1-nano-2025-04-14"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `"o4-mini"` - - `type: "computer"` + - `"o4-mini-2025-04-16"` - The type of the computer tool. Always `computer`. + - `"o3"` - - `"computer"` + - `"o3-2025-04-16"` - - `ComputerUsePreview object { display_height, display_width, environment, type }` + - `"o3-mini"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `"o3-mini-2025-01-31"` - - `display_height: number` + - `"o1"` - The height of the computer display. + - `"o1-2024-12-17"` - - `display_width: number` + - `"o1-preview"` - The width of the computer display. + - `"o1-preview-2024-09-12"` - - `environment: "windows" or "mac" or "linux" or 2 more` + - `"o1-mini"` - The type of computer environment to control. + - `"o1-mini-2024-09-12"` - - `"windows"` + - `"gpt-4o"` - - `"mac"` + - `"gpt-4o-2024-11-20"` - - `"linux"` + - `"gpt-4o-2024-08-06"` - - `"ubuntu"` + - `"gpt-4o-2024-05-13"` - - `"browser"` + - `"gpt-4o-audio-preview"` - - `type: "computer_use_preview"` + - `"gpt-4o-audio-preview-2024-10-01"` - The type of the computer use tool. Always `computer_use_preview`. + - `"gpt-4o-audio-preview-2024-12-17"` - - `"computer_use_preview"` + - `"gpt-4o-audio-preview-2025-06-03"` - - `WebSearch object { type, filters, search_context_size, user_location }` + - `"gpt-4o-mini-audio-preview"` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `"gpt-4o-mini-audio-preview-2024-12-17"` - - `type: "web_search" or "web_search_2025_08_26"` + - `"gpt-4o-search-preview"` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `"gpt-4o-mini-search-preview"` - - `"web_search"` + - `"gpt-4o-search-preview-2025-03-11"` - - `"web_search_2025_08_26"` + - `"gpt-4o-mini-search-preview-2025-03-11"` - - `filters: optional object { allowed_domains }` + - `"chatgpt-4o-latest"` - Filters for the search. + - `"codex-mini-latest"` - - `allowed_domains: optional array of string` + - `"gpt-4o-mini"` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `"gpt-4o-mini-2024-07-18"` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `"gpt-4-turbo"` - - `search_context_size: optional "low" or "medium" or "high"` + - `"gpt-4-turbo-2024-04-09"` - 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-4-0125-preview"` - - `"low"` + - `"gpt-4-turbo-preview"` - - `"medium"` + - `"gpt-4-1106-preview"` - - `"high"` + - `"gpt-4-vision-preview"` - - `user_location: optional object { city, country, region, 2 more }` + - `"gpt-4"` - The approximate location of the user. + - `"gpt-4-0314"` - - `city: optional string` + - `"gpt-4-0613"` - Free text input for the city of the user, e.g. `San Francisco`. + - `"gpt-4-32k"` - - `country: optional string` + - `"gpt-4-32k-0314"` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `"gpt-4-32k-0613"` - - `region: optional string` + - `"gpt-3.5-turbo"` - Free text input for the region of the user, e.g. `California`. + - `"gpt-3.5-turbo-16k"` - - `timezone: optional string` + - `"gpt-3.5-turbo-0301"` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `"gpt-3.5-turbo-0613"` - - `type: optional "approximate"` + - `"gpt-3.5-turbo-1106"` - The type of location approximation. Always `approximate`. + - `"gpt-3.5-turbo-0125"` - - `"approximate"` + - `"gpt-3.5-turbo-16k-0613"` - - `Mcp object { server_label, type, allowed_callers, 9 more }` + - `"o1-pro"` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `"o1-pro-2025-03-19"` - - `server_label: string` + - `"o3-pro"` - A label for this MCP server, used to identify it in tool calls. + - `"o3-pro-2025-06-10"` - - `type: "mcp"` + - `"o3-deep-research"` - The type of the MCP tool. Always `mcp`. + - `"o3-deep-research-2025-06-26"` - - `"mcp"` + - `"o4-mini-deep-research"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"o4-mini-deep-research-2025-06-26"` - The tool invocation context(s). + - `"computer-use-preview"` - - `"direct"` + - `"computer-use-preview-2025-03-11"` - - `"programmatic"` + - `"gpt-5-codex"` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + - `"gpt-5-pro"` - List of allowed tool names or a filter object. + - `"gpt-5-pro-2025-10-06"` - - `McpAllowedTools = array of string` + - `"gpt-5.1-codex-max"` - A string array of allowed tool names + - `string` - - `McpToolFilter object { read_only, tool_names }` + - `object: "response"` - A filter object to specify which tools are allowed. + The object type of this resource - always set to `response`. - - `read_only: optional boolean` + - `"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. + - `output: array of BetaResponseOutputItem` - - `tool_names: optional array of string` + An array of content items generated by the model. - List of allowed tool names. + - 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. - - `authorization: optional string` + - `BetaResponseOutputMessage object { id, content, role, 4 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. + An output message from the model. - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + - `FileSearchCall object { id, queries, status, 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + The results of a file search tool call. See the + [file search guide](/docs/guides/tools-file-search) for more information. - Currently supported `connector_id` values are: + - `id: string` - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + The unique ID of the file search tool call. - - `"connector_dropbox"` + - `queries: array of string` - - `"connector_gmail"` + The queries used to search for files. - - `"connector_googlecalendar"` + - `status: "in_progress" or "searching" or "completed" or 2 more` - - `"connector_googledrive"` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `"connector_microsoftteams"` + - `"in_progress"` - - `"connector_outlookcalendar"` + - `"searching"` - - `"connector_outlookemail"` + - `"completed"` - - `"connector_sharepoint"` + - `"incomplete"` - - `defer_loading: optional boolean` + - `"failed"` - Whether this MCP tool is deferred and discovered via tool search. + - `type: "file_search_call"` - - `headers: optional map[string]` + The type of the file search tool call. Always `file_search_call`. - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `"file_search_call"` - - `require_approval: optional object { always, never } or "always" or "never"` + - `agent: optional object { agent_name }` - Specify which of the MCP server's tools require approval. + The agent that produced this item. - - `McpToolApprovalFilter object { always, never }` + - `agent_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 canonical name of the agent that produced this item. - - `always: optional object { read_only, tool_names }` + - `results: optional array of object { attributes, file_id, filename, 2 more }` - A filter object to specify which tools are allowed. + The results of the file search tool call. - - `read_only: optional boolean` + - `attributes: optional map[string or number or 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. + 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. - - `tool_names: optional array of string` + - `string` - List of allowed tool names. + - `number` - - `never: optional object { read_only, tool_names }` + - `boolean` - A filter object to specify which tools are allowed. + - `file_id: optional string` - - `read_only: optional boolean` + The unique ID 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. + - `filename: optional string` - - `tool_names: optional array of string` + The name of the file. - List of allowed tool names. + - `score: optional number` - - `McpToolApprovalSetting = "always" or "never"` + The relevance score of the file - a value between 0 and 1. - 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: optional string` - - `"always"` + The text that was retrieved from the file. - - `"never"` + - `FunctionCall object { arguments, call_id, name, 6 more }` - - `server_description: optional string` + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. - Optional description of the MCP server, used to provide more context. + - `arguments: string` - - `server_url: optional string` + A JSON string of the arguments to pass to the function. - 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 function 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. + - `name: string` - - `CodeInterpreter object { container, type, allowed_callers }` + The name of the function to run. - A tool that runs Python code to help generate a response to a prompt. + - `type: "function_call"` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + The type of the function tool call. Always `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. + - `"function_call"` - - `string` + - `id: optional string` - The container ID. + The unique ID of the function tool call. - - `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"` + - `caller: optional object { type } or object { caller_id, type }` - - `file_ids: optional array of string` + The execution context that produced this tool call. - An optional list of uploaded files to make available to your code. + - `Direct object { type }` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `type: "direct"` - The memory limit for the code interpreter container. + - `"direct"` - - `"1g"` + - `Program object { caller_id, type }` - - `"4g"` + - `caller_id: string` - - `"16g"` + The call ID of the program item that produced this tool call. - - `"64g"` + - `type: "program"` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `"program"` - Network access policy for the container. + - `namespace: optional string` - - `BetaContainerNetworkPolicyDisabled object { type }` + The namespace of the function to run. - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `type: "code_interpreter"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The type of the code interpreter tool. Always `code_interpreter`. + - `"in_progress"` - - `"code_interpreter"` + - `"completed"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"incomplete"` - 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. - - `ProgrammaticToolCalling object { type }` + - `call_id: string` - - `type: "programmatic_tool_calling"` + The unique ID of the function tool call generated by the model. - The type of the tool. Always `programmatic_tool_calling`. + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `"programmatic_tool_calling"` + The output from the function call generated by your code. + Can be a string or an list of output content. - - `ImageGeneration object { type, action, background, 9 more }` + - `StringOutput = string` - A tool that generates images using the GPT image models. + A string of the output of the function call. - - `type: "image_generation"` + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - The type of the image generation tool. Always `image_generation`. + Text, image, or file output of the function call. - - `"image_generation"` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `action: optional "generate" or "edit" or "auto"` + A text input to the model. - Whether to generate a new image or edit an existing image. Default: `auto`. + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `"generate"` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `"edit"` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `"auto"` + A file input to the model. - - `background: optional "transparent" or "opaque" or "auto"` + - `status: "in_progress" or "completed" or "incomplete"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + - `"in_progress"` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `"completed"` - - `"transparent"` + - `"incomplete"` - - `"opaque"` + - `type: "function_call_output"` - - `"auto"` + The type of the function tool call output. Always `function_call_output`. - - `input_fidelity: optional "high" or "low"` + - `"function_call_output"` - 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 produced this item. - - `"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). + - `caller: optional object { type } or object { caller_id, type }` - - `file_id: optional string` + The execution context that produced this tool call. - File ID for the mask image. + - `Direct object { type }` - - `image_url: optional string` + - `type: "direct"` - Base64-encoded mask image. + The caller type. Always `direct`. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `"direct"` - The image generation model to use. Default: `gpt-image-1`. + - `Program object { caller_id, type }` - - `string` + - `caller_id: string` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + The call ID of the program item that produced this tool call. - The image generation model to use. Default: `gpt-image-1`. + - `type: "program"` - - `"gpt-image-1"` + The caller type. Always `program`. - - `"gpt-image-1-mini"` + - `"program"` - - `"gpt-image-2"` + - `created_by: optional string` - - `"gpt-image-2-2026-04-21"` + The identifier of the actor that created the item. - - `"gpt-image-1.5"` + - `AgentMessage object { id, author, content, 3 more }` - - `"chatgpt-image-latest"` + - `id: string` - - `moderation: optional "auto" or "low"` + The unique ID of the agent message. - Moderation level for the generated image. Default: `auto`. + - `author: string` - - `"auto"` + The sending agent identity. - - `"low"` + - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` - - `output_compression: optional number` + Encrypted content sent between agents. - Compression level for the output image. Default: 100. + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `output_format: optional "png" or "webp" or "jpeg"` + A text input to the model. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - - `"png"` + A text output from the model. - - `"webp"` + - `Text object { text, type }` - - `"jpeg"` + A text content. - - `partial_images: optional number` + - `text: string` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `type: "text"` - - `quality: optional "low" or "medium" or "high" or "auto"` + - `"text"` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `SummaryText object { text, type }` - - `"low"` + A summary text from the model. - - `"medium"` + - `text: string` - - `"high"` + A summary of the reasoning output from the model so far. - - `"auto"` + - `type: "summary_text"` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + The type of the object. Always `summary_text`. - 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`. + - `"summary_text"` - - `string` + - `ReasoningText object { text, type }` - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + Reasoning text from 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`. + - `text: string` - - `"1024x1024"` + The reasoning text from the model. - - `"1024x1536"` + - `type: "reasoning_text"` - - `"1536x1024"` + The type of the reasoning text. Always `reasoning_text`. - - `"auto"` + - `"reasoning_text"` - - `LocalShell object { type }` + - `BetaResponseOutputRefusal object { refusal, type }` - A tool that allows the model to execute shell commands in a local environment. + A refusal from the model. - - `type: "local_shell"` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - The type of the local shell tool. Always `local_shell`. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `"local_shell"` + - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` - - `Shell object { type, allowed_callers, environment }` + A screenshot of a computer. - A tool that allows the model to execute shell commands. + - `detail: "low" or "high" or "auto" or "original"` - - `type: "shell"` + 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 shell tool. Always `shell`. + - `"low"` - - `"shell"` + - `"high"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"auto"` - The tool invocation context(s). + - `"original"` - - `"direct"` + - `file_id: string` - - `"programmatic"` + The identifier of an uploaded file that contains the screenshot. - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + - `image_url: string` - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + The URL of the screenshot image. - - `BetaLocalEnvironment object { type, skills }` + - `type: "computer_screenshot"` - - `BetaContainerReference object { container_id, type }` + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `Custom object { name, type, allowed_callers, 3 more }` + - `"computer_screenshot"` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `prompt_cache_breakpoint: optional object { mode }` - - `name: string` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The name of the custom tool, used to identify it in tool calls. + - `mode: "explicit"` - - `type: "custom"` + The breakpoint mode. Always `explicit`. - The type of the custom tool. Always `custom`. + - `"explicit"` - - `"custom"` + - `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). + - `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 tool should be deferred and discovered via tool search. + - `type: "encrypted_content"` - - `description: optional string` + The type of the input item. Always `encrypted_content`. - Optional description of the custom tool, used to provide more context. + - `"encrypted_content"` - - `format: optional object { type } or object { definition, syntax, type }` + - `recipient: string` - The input format for the custom tool. Default is unconstrained text. + The destination agent identity. - - `Text object { type }` + - `type: "agent_message"` - Unconstrained free-form text. + The type of the item. Always `agent_message`. - - `type: "text"` + - `"agent_message"` - 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` + - `MultiAgentCall object { id, action, arguments, 3 more }` - The grammar definition. + - `id: string` - - `syntax: "lark" or "regex"` + The unique ID of the multi-agent call item. - The syntax of the grammar definition. One of `lark` or `regex`. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `"lark"` + The multi-agent action to execute. - - `"regex"` + - `"spawn_agent"` - - `type: "grammar"` + - `"interrupt_agent"` - Grammar format. Always `grammar`. + - `"list_agents"` - - `"grammar"` + - `"send_message"` - - `Namespace object { description, name, tools, type }` + - `"followup_task"` - Groups function/custom tools under a shared namespace. + - `"wait_agent"` - - `description: string` + - `arguments: string` - A description of the namespace shown to the model. + The JSON string of arguments generated for the action. - - `name: string` + - `call_id: string` - The namespace name used in tool calls (for example, `crm`). + The unique ID linking this call to its output. - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + - `type: "multi_agent_call"` - The function/custom tools available inside this namespace. + The type of the multi-agent call. Always `multi_agent_call`. - - `Function object { name, type, allowed_callers, 5 more }` + - `"multi_agent_call"` - - `name: string` + - `agent: optional object { agent_name }` - - `type: "function"` + The agent that produced this item. - - `"function"` + - `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). + - `MultiAgentCallOutput object { id, action, call_id, 3 more }` - - `"direct"` + - `id: string` - - `"programmatic"` + The unique ID of the multi-agent call output item. - - `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 produced this result. - - `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 }` + - `call_id: string` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The unique ID of the multi-agent call. - - `name: string` + - `output: array of BetaResponseOutputText` - The name of the custom tool, used to identify it in tool calls. + Text output returned by the multi-agent action. - - `type: "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 }` - The type of the custom tool. Always `custom`. + The annotations of the text output. - - `"custom"` + - `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`. - - `defer_loading: optional boolean` + - `type: "multi_agent_call_output"` - Whether this tool should be deferred and discovered via tool search. + The type of the multi-agent result. Always `multi_agent_call_output`. - - `description: optional string` + - `"multi_agent_call_output"` - 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. + - `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`. + - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` - - `country: optional string` + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - 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 computer call. - Free text input for the region of the user, e.g. `California`. + - `call_id: string` - - `timezone: optional string` + An identifier used when responding to the tool call with output. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `pending_safety_checks: array of object { id, code, message }` - - `ApplyPatch object { type, allowed_callers }` + The pending safety checks for the computer call. - Allows the assistant to create, delete, or update files using unified diffs. + - `id: string` - - `type: "apply_patch"` + The ID of the pending safety check. - The type of the tool. Always `apply_patch`. + - `code: optional string` - - `"apply_patch"` + 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"` + - `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. - - `top_p: number` + - `"in_progress"` - 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. + - `"completed"` - We generally recommend altering this or `temperature` but not both. + - `"incomplete"` - - `background: optional boolean` + - `type: "computer_call"` - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + The type of the computer call. Always `computer_call`. - - `completed_at: optional number` + - `"computer_call"` - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + - `action: optional BetaComputerAction` - - `conversation: optional object { id }` + A click action. - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + - `actions: optional BetaComputerActionList` - - `id: string` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - The unique ID of the conversation that this response was associated with. + - `agent: optional object { agent_name }` - - `max_output_tokens: optional number` + The agent that produced this item. - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + - `agent_name: string` - - `max_tool_calls: optional number` + The canonical name of the agent that produced this item. - 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. + - `ComputerCallOutput object { id, call_id, output, 5 more }` - - `moderation: optional object { input, output }` + - `id: string` - Moderation results for the response input and output, if moderated completions were requested. + The unique ID of the computer call tool output. - - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + - `call_id: string` - Moderation for the response input. + The ID of the computer tool call that produced the output. - - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` + - `output: BetaResponseComputerToolCallOutputScreenshot` - A moderation result produced for the response input or output. + A computer screenshot image used with the computer use tool. - - `categories: map[boolean]` + - `status: "completed" or "incomplete" or "failed" or "in_progress"` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `category_applied_input_types: map[array of "text" or "image"]` + - `"completed"` - Which modalities of input are reflected by the score for each category. + - `"incomplete"` - - `"text"` + - `"failed"` - - `"image"` + - `"in_progress"` - - `category_scores: map[number]` + - `type: "computer_call_output"` - A dictionary of moderation categories to scores. + The type of the computer tool call output. Always `computer_call_output`. - - `flagged: boolean` + - `"computer_call_output"` - A boolean indicating whether the content was flagged by any category. + - `acknowledged_safety_checks: optional array of object { id, code, message }` - - `model: string` + The safety checks reported by the API that have been acknowledged by the + developer. - The moderation model that produced this result. + - `id: string` - - `type: "moderation_result"` + The ID of the pending safety check. - The object type, which was always `moderation_result` for successful moderation results. + - `code: optional string` - - `"moderation_result"` + The type of the pending safety check. - - `Error object { code, message, type }` + - `message: optional string` - An error produced while attempting moderation for the response input or output. + Details about the pending safety check. - - `code: string` + - `agent: optional object { agent_name }` - The error code. + The agent that produced this item. - - `message: string` + - `agent_name: string` - The error message. + The canonical name of the agent that produced this item. - - `type: "error"` + - `created_by: optional string` - The object type, which was always `error` for moderation failures. + The identifier of the actor that created the item. - - `"error"` + - `Reasoning object { id, summary, type, 4 more }` - - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, 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). - Moderation for the response output. + - `id: string` - - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` + The unique identifier of the reasoning content. - A moderation result produced for the response input or output. + - `summary: array of object { text, type }` - - `categories: map[boolean]` + Reasoning summary content. - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `text: string` - - `category_applied_input_types: map[array of "text" or "image"]` + A summary of the reasoning output from the model so far. - Which modalities of input are reflected by the score for each category. + - `type: "summary_text"` - - `"text"` + The type of the object. Always `summary_text`. - - `"image"` + - `"summary_text"` - - `category_scores: map[number]` + - `type: "reasoning"` - A dictionary of moderation categories to scores. + The type of the object. Always `reasoning`. - - `flagged: boolean` + - `"reasoning"` - A boolean indicating whether the content was flagged by any category. + - `agent: optional object { agent_name }` - - `model: string` + The agent that produced this item. - The moderation model that produced this result. + - `agent_name: string` - - `type: "moderation_result"` + The canonical name of the agent that produced this item. - The object type, which was always `moderation_result` for successful moderation results. + - `content: optional array of object { text, type }` - - `"moderation_result"` + Reasoning text content. - - `Error object { code, message, type }` + - `text: string` - An error produced while attempting moderation for the response input or output. + The reasoning text from the model. - - `code: string` + - `type: "reasoning_text"` - The error code. + The type of the reasoning text. Always `reasoning_text`. - - `message: string` + - `"reasoning_text"` - The error message. + - `encrypted_content: optional string` - - `type: "error"` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - The object type, which was always `error` for moderation failures. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"error"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `previous_response_id: optional string` + - `"in_progress"` - The unique ID of the previous response to the model. Use this to - create multi-turn conversations. Learn more about - [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + - `"completed"` - - `prompt: optional BetaResponsePrompt` + - `"incomplete"` - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + - `Program object { id, call_id, code, 3 more }` - `id: string` - The unique identifier of the prompt template to use. + The unique ID of the program item. - - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` + - `call_id: string` - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. + The stable call ID of the program item. - - `string` + - `code: string` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + The JavaScript source executed by programmatic tool calling. - A text input to the model. + - `fingerprint: string` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + Opaque program replay fingerprint that must be round-tripped. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `type: "program"` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + The type of the item. Always `program`. - A file input to the model. + - `"program"` - - `version: optional string` + - `agent: optional object { agent_name }` - Optional version of the prompt template. + The agent that produced this item. - - `prompt_cache_key: optional string` + - `agent_name: string` - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + The canonical name of the agent that produced this item. - - `prompt_cache_options: optional object { mode, ttl }` + - `ProgramOutput object { id, call_id, result, 3 more }` - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + - `id: string` - - `mode: "implicit" or "explicit"` + The unique ID of the program output item. - Whether implicit prompt-cache breakpoints were enabled. + - `call_id: string` - - `"implicit"` + The call ID of the program item. - - `"explicit"` + - `result: string` - - `ttl: "30m"` + The result produced by the program item. - The minimum lifetime applied to each cache breakpoint. + - `status: "completed" or "incomplete"` - - `"30m"` + The terminal status of the program output item. - - `prompt_cache_retention: optional "in_memory" or "24h"` + - `"completed"` - Deprecated. Use `prompt_cache_options.ttl` instead. + - `"incomplete"` - 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](https://platform.openai.com/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: "program_output"` - 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 `program_output`. - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `"program_output"` - - `"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). + - `ToolSearchCall object { id, arguments, call_id, 5 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. - When returned on a response, this is the effective reasoning context mode - used for the response. + The unique ID of the tool search call item. - - `"auto"` + - `arguments: unknown` - - `"current_turn"` + Arguments used for the tool search call. - - `"all_turns"` + - `call_id: string` - - `effort: optional "none" or "minimal" or "low" or 4 more` + The unique ID of the tool search call generated by 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. + - `execution: "server" or "client"` - - `"none"` + Whether tool search was executed by the server or by the client. - - `"minimal"` + - `"server"` - - `"low"` + - `"client"` - - `"medium"` + - `status: "in_progress" or "completed" or "incomplete"` - - `"high"` + The status of the tool search call item that was recorded. - - `"xhigh"` + - `"in_progress"` - - `"max"` + - `"completed"` - - `generate_summary: optional "auto" or "concise" or "detailed"` + - `"incomplete"` - **Deprecated:** use `summary` instead. + - `type: "tool_search_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`. + The type of the item. Always `tool_search_call`. - - `"auto"` + - `"tool_search_call"` - - `"concise"` + - `agent: optional object { agent_name }` - - `"detailed"` + The agent that produced this item. - - `mode: optional string or "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. + - `created_by: optional string` - - `string` + The identifier of the actor that created the item. - - `"standard" or "pro"` + - `ToolSearchOutput object { id, call_id, execution, 5 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 tool search output item. - - `"standard"` + - `call_id: string` - - `"pro"` + The unique ID of the tool search call generated by the model. - - `summary: optional "auto" or "concise" or "detailed"` + - `execution: "server" or "client"` - 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 tool search was executed by the server or by the client. - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + - `"server"` - - `"auto"` + - `"client"` - - `"concise"` + - `status: "in_progress" or "completed" or "incomplete"` - - `"detailed"` + The status of the tool search output item that was recorded. - - `safety_identifier: optional string` + - `"in_progress"` - 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](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `"completed"` - - `service_tier: optional "auto" or "default" or "flex" or 2 more` + - `"incomplete"` - Specifies the processing type used for serving the request. + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 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](https://platform.openai.com/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 loaded tool definitions returned by tool search. - 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. + - `Function object { name, parameters, strict, 5 more }` - - `"auto"` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `"default"` + - `name: string` - - `"flex"` + The name of the function to call. - - `"scale"` + - `parameters: map[unknown]` - - `"priority"` + A JSON schema object describing the parameters of the function. - - `status: optional BetaResponseStatus` + - `strict: boolean` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + Whether strict parameter validation is enforced for this function tool. - - `"completed"` + - `type: "function"` - - `"failed"` + The type of the function tool. Always `function`. - - `"in_progress"` + - `"function"` - - `"cancelled"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"queued"` + The tool invocation context(s). - - `"incomplete"` + - `"direct"` - - `text: optional BetaResponseTextConfig` + - `"programmatic"` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + - `defer_loading: optional boolean` - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + Whether this function is deferred and loaded via tool search. - - `format: optional BetaResponseFormatTextConfig` + - `description: optional string` - An object specifying the format that the model must output. + A description of the function. Used by the model to determine whether or not to call the function. - Configuring `{ "type": "json_schema" }` enables Structured Outputs, - which ensures the model will match your supplied JSON schema. Learn more in the - [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `output_schema: optional map[unknown]` - The default format is `{ "type": "text" }` with no additional options. + A JSON schema object describing the JSON value encoded in string outputs for this function. - **Not recommended for gpt-4o and newer models:** + - `FileSearch object { type, vector_store_ids, filters, 2 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 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). - - `Text object { type }` + - `type: "file_search"` - Default response format. Used to generate text responses. + The type of the file search tool. Always `file_search`. - - `type: "text"` + - `"file_search"` - The type of response format being defined. Always `text`. + - `vector_store_ids: array of string` - - `"text"` + The IDs of the vector stores to search. - - `BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` + - `filters: optional object { key, type, value } or object { filters, type }` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + A filter to apply. - - `name: string` + - `ComparisonFilter object { key, type, value }` - 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 used to compare a specified attribute key to a given value using a defined comparison operation. - - `schema: map[unknown]` + - `key: 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 key to compare against the value. - - `type: "json_schema"` + - `type: "eq" or "ne" or "gt" or 5 more` - The type of response format being defined. Always `json_schema`. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `"json_schema"` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `description: optional string` + - `"eq"` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `"ne"` - - `strict: optional boolean` + - `"gt"` - 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](https://platform.openai.com/docs/guides/structured-outputs). + - `"gte"` - - `JSONObject object { type }` + - `"lt"` - 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. + - `"lte"` - - `type: "json_object"` + - `"in"` - The type of response format being defined. Always `json_object`. + - `"nin"` - - `"json_object"` + - `value: string or number or boolean or array of string or number` - - `verbosity: optional "low" or "medium" or "high"` + The value to compare against the attribute key; supports string, number, or boolean types. - 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`. + - `string` - - `"low"` + - `number` - - `"medium"` + - `boolean` - - `"high"` + - `array of string or number` - - `top_logprobs: optional number` + - `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. + - `number` - - `truncation: optional "auto" or "disabled"` + - `CompoundFilter object { filters, type }` - The truncation strategy to use for the model response. + Combine multiple filters using `and` or `or`. - - `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. + - `filters: array of object { key, type, value } or unknown` - - `"auto"` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `"disabled"` + - `ComparisonFilter object { key, type, value }` - - `usage: optional BetaResponseUsage` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + - `key: string` - - `input_tokens: number` + The key to compare against the value. - The number of input tokens. + - `type: "eq" or "ne" or "gt" or 5 more` - - `input_tokens_details: object { cache_write_tokens, cached_tokens }` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - A detailed breakdown of the input tokens. + - `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 - - `cache_write_tokens: number` + - `"eq"` - The number of input tokens that were written to the cache. + - `"ne"` - - `cached_tokens: number` + - `"gt"` - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + - `"gte"` - - `output_tokens: number` + - `"lt"` - The number of output tokens. + - `"lte"` - - `output_tokens_details: object { reasoning_tokens }` + - `"in"` - A detailed breakdown of the output tokens. + - `"nin"` - - `reasoning_tokens: number` + - `value: string or number or boolean or array of string or number` - The number of reasoning tokens. + The value to compare against the attribute key; supports string, number, or boolean types. - - `total_tokens: number` + - `string` - The total number of tokens used. + - `number` - - `user: optional string` + - `boolean` - 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](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `array of string or number` -### Example + - `string` -```http -curl https://api.openai.com/v1/responses/$RESPONSE_ID/cancel \ - -X POST \ - -H 'OpenAI-Beta: assistants=v2' \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + - `number` -#### Response + - `unknown` -```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" - } - ], - "text": "text", - "type": "output_text", - "logprobs": [ - { - "token": "token", - "bytes": [ - 0 - ], - "logprob": 0, - "top_logprobs": [ - { - "token": "token", - "bytes": [ - 0 - ], - "logprob": 0 - } - ] - } - ] - } - ], - "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" -} -``` + - `type: "and" or "or"` -### Example + Type of operation: `and` or `or`. + + - `"and"` -```http -curl -X POST https://api.openai.com/v1/responses/resp_123/cancel \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + - `"or"` -#### Response + - `max_num_results: optional number` -```json -{ - "id": "resp_67cb71b351908190a308f3859487620d06981a8637e6bc44", - "object": "response", - "created_at": 1741386163, - "status": "cancelled", - "background": true, - "completed_at": null, - "error": null, - "incomplete_details": null, - "instructions": null, - "max_output_tokens": null, - "model": "gpt-4o-2024-08-06", - "output": [ - { - "type": "message", - "id": "msg_67cb71b3c2b0819084d481baaaf148f206981a8637e6bc44", - "status": "in_progress", - "role": "assistant", - "content": [ - { - "type": "output_text", - "text": "Silent circuits hum, \nThoughts emerge in data streams— \nDigital dawn breaks.", - "annotations": [] - } - ] - } - ], - "parallel_tool_calls": true, - "previous_response_id": null, - "reasoning": { - "effort": null, - "summary": null - }, - "store": true, - "temperature": 1.0, - "text": { - "format": { - "type": "text" - } - }, - "tool_choice": "auto", - "tools": [], - "top_p": 1.0, - "truncation": "disabled", - "usage": null, - "user": null, - "metadata": {} -} -``` + The maximum number of results to return. This number should be between 1 and 50 inclusive. -## Compact a response + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` -**post** `/responses/compact?beta=true` + Ranking options for search. -Compact a response + - `hybrid_search: optional object { embedding_weight, text_weight }` -### Header Parameters + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. -- `"openai-beta": optional array of "responses_multi_agent=v1"` + - `embedding_weight: number` - - `"responses_multi_agent=v1"` + The weight of the embedding in the reciprocal ranking fusion. -### Body Parameters + - `text_weight: number` -- `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` + The weight of the text in the reciprocal ranking fusion. - 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](https://platform.openai.com/docs/models) to browse and compare available models. + - `ranker: optional "auto" or "default-2024-11-15"` - - `"gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more` + The ranker to use for the file search. - 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](https://platform.openai.com/docs/models) to browse and compare available models. + - `"auto"` - - `"gpt-5.6-sol"` + - `"default-2024-11-15"` - - `"gpt-5.6-terra"` + - `score_threshold: optional number` - - `"gpt-5.6-luna"` + 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-5.4"` + - `Computer object { type }` - - `"gpt-5.4-mini"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"gpt-5.4-nano"` + - `type: "computer"` - - `"gpt-5.4-mini-2026-03-17"` + The type of the computer tool. Always `computer`. - - `"gpt-5.4-nano-2026-03-17"` + - `"computer"` - - `"gpt-5.3-chat-latest"` + - `ComputerUsePreview object { display_height, display_width, environment, type }` - - `"gpt-5.2"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"gpt-5.2-2025-12-11"` + - `display_height: number` - - `"gpt-5.2-chat-latest"` + The height of the computer display. - - `"gpt-5.2-pro"` + - `display_width: number` - - `"gpt-5.2-pro-2025-12-11"` + The width of the computer display. - - `"gpt-5.1"` + - `environment: "windows" or "mac" or "linux" or 2 more` - - `"gpt-5.1-2025-11-13"` + The type of computer environment to control. - - `"gpt-5.1-codex"` + - `"windows"` - - `"gpt-5.1-mini"` + - `"mac"` - - `"gpt-5.1-chat-latest"` + - `"linux"` - - `"gpt-5"` + - `"ubuntu"` - - `"gpt-5-mini"` + - `"browser"` - - `"gpt-5-nano"` + - `type: "computer_use_preview"` - - `"gpt-5-2025-08-07"` + The type of the computer use tool. Always `computer_use_preview`. - - `"gpt-5-mini-2025-08-07"` + - `"computer_use_preview"` - - `"gpt-5-nano-2025-08-07"` + - `WebSearch object { type, filters, search_context_size, user_location }` - - `"gpt-5-chat-latest"` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - - `"gpt-4.1"` + - `type: "web_search" or "web_search_2025_08_26"` - - `"gpt-4.1-mini"` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `"gpt-4.1-nano"` + - `"web_search"` - - `"gpt-4.1-2025-04-14"` + - `"web_search_2025_08_26"` - - `"gpt-4.1-mini-2025-04-14"` + - `filters: optional object { allowed_domains }` - - `"gpt-4.1-nano-2025-04-14"` + Filters for the search. - - `"o4-mini"` + - `allowed_domains: optional array of string` - - `"o4-mini-2025-04-16"` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `"o3"` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `"o3-2025-04-16"` + - `search_context_size: optional "low" or "medium" or "high"` - - `"o3-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. - - `"o3-mini-2025-01-31"` + - `"low"` - - `"o1"` + - `"medium"` - - `"o1-2024-12-17"` + - `"high"` - - `"o1-preview"` + - `user_location: optional object { city, country, region, 2 more }` - - `"o1-preview-2024-09-12"` + The approximate location of the user. - - `"o1-mini"` + - `city: optional string` - - `"o1-mini-2024-09-12"` + Free text input for the city of the user, e.g. `San Francisco`. - - `"gpt-4o"` + - `country: optional string` - - `"gpt-4o-2024-11-20"` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `"gpt-4o-2024-08-06"` + - `region: optional string` - - `"gpt-4o-2024-05-13"` + Free text input for the region of the user, e.g. `California`. - - `"gpt-4o-audio-preview"` + - `timezone: optional string` - - `"gpt-4o-audio-preview-2024-10-01"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `"gpt-4o-audio-preview-2024-12-17"` + - `type: optional "approximate"` - - `"gpt-4o-audio-preview-2025-06-03"` + The type of location approximation. Always `approximate`. - - `"gpt-4o-mini-audio-preview"` + - `"approximate"` - - `"gpt-4o-mini-audio-preview-2024-12-17"` + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `"gpt-4o-search-preview"` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - - `"gpt-4o-mini-search-preview"` + - `server_label: string` - - `"gpt-4o-search-preview-2025-03-11"` + A label for this MCP server, used to identify it in tool calls. - - `"gpt-4o-mini-search-preview-2025-03-11"` + - `type: "mcp"` - - `"chatgpt-4o-latest"` + The type of the MCP tool. Always `mcp`. - - `"codex-mini-latest"` + - `"mcp"` - - `"gpt-4o-mini"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"gpt-4o-mini-2024-07-18"` + The tool invocation context(s). - - `"gpt-4-turbo"` + - `"direct"` - - `"gpt-4-turbo-2024-04-09"` + - `"programmatic"` - - `"gpt-4-0125-preview"` + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `"gpt-4-turbo-preview"` + List of allowed tool names or a filter object. - - `"gpt-4-1106-preview"` + - `McpAllowedTools = array of string` - - `"gpt-4-vision-preview"` + A string array of allowed tool names - - `"gpt-4"` + - `McpToolFilter object { read_only, tool_names }` - - `"gpt-4-0314"` + A filter object to specify which tools are allowed. - - `"gpt-4-0613"` + - `read_only: optional boolean` - - `"gpt-4-32k"` + 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-32k-0314"` + - `tool_names: optional array of string` - - `"gpt-4-32k-0613"` + List of allowed tool names. - - `"gpt-3.5-turbo"` + - `authorization: optional string` - - `"gpt-3.5-turbo-16k"` + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - - `"gpt-3.5-turbo-0301"` + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `"gpt-3.5-turbo-0613"` + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). - - `"gpt-3.5-turbo-1106"` + Currently supported `connector_id` values are: - - `"gpt-3.5-turbo-0125"` + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - - `"gpt-3.5-turbo-16k-0613"` + - `"connector_dropbox"` - - `"o1-pro"` + - `"connector_gmail"` - - `"o1-pro-2025-03-19"` + - `"connector_googlecalendar"` - - `"o3-pro"` + - `"connector_googledrive"` - - `"o3-pro-2025-06-10"` + - `"connector_microsoftteams"` - - `"o3-deep-research"` + - `"connector_outlookcalendar"` - - `"o3-deep-research-2025-06-26"` + - `"connector_outlookemail"` - - `"o4-mini-deep-research"` + - `"connector_sharepoint"` - - `"o4-mini-deep-research-2025-06-26"` + - `defer_loading: optional boolean` - - `"computer-use-preview"` + Whether this MCP tool is deferred and discovered via tool search. - - `"computer-use-preview-2025-03-11"` + - `headers: optional map[string]` - - `"gpt-5-codex"` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `"gpt-5-pro"` + - `require_approval: optional object { always, never } or "always" or "never"` - - `"gpt-5-pro-2025-10-06"` + Specify which of the MCP server's tools require approval. - - `"gpt-5.1-codex-max"` + - `McpToolApprovalFilter object { always, never }` - - `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. -- `input: optional string or array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + - `always: optional object { read_only, tool_names }` - Text, image, or file inputs to the model, used to generate a response + A filter object to specify which tools are allowed. - - `string` + - `read_only: optional boolean` - A text input to the model, equivalent to a text input with the `user` role. + 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. - - `array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + - `tool_names: optional array of string` - A list of one or many input items to the model, containing different content types. + List of allowed tool names. - - `BetaEasyInputMessage object { content, role, phase, type }` + - `never: optional object { read_only, tool_names }` - 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 filter object to specify which tools are allowed. - - `content: string or BetaResponseInputMessageContentList` + - `read_only: optional boolean` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + 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. - - `TextInput = string` + - `tool_names: optional array of string` - A text input to the model. + List of allowed tool names. - - `BetaResponseInputMessageContentList = array of BetaResponseInputContent` + - `McpToolApprovalSetting = "always" or "never"` - A list of one or many input items to the model, containing different content - types. + 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. - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `"always"` - A text input to the model. + - `"never"` - - `text: string` + - `server_description: optional string` - The text input to the model. + Optional description of the MCP server, used to provide more context. - - `type: "input_text"` + - `server_url: optional string` - The type of the input item. Always `input_text`. + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `"input_text"` + - `tunnel_id: optional string` - - `prompt_cache_breakpoint: optional object { mode }` + 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. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `CodeInterpreter object { container, type, allowed_callers }` - - `mode: "explicit"` + A tool that runs Python code to help generate a response to a prompt. - The breakpoint mode. Always `explicit`. + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `"explicit"` + 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. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `string` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The container ID. - - `detail: "low" or "high" or "auto" or "original"` + - `CodeInterpreterToolAuto 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`. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `"low"` + - `type: "auto"` - - `"high"` + Always `auto`. - `"auto"` - - `"original"` + - `file_ids: optional array of string` - - `type: "input_image"` + An optional list of uploaded files to make available to your code. - The type of the input item. Always `input_image`. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `"input_image"` + The memory limit for the code interpreter container. - - `file_id: optional string` + - `"1g"` - The ID of the file to be sent to the model. + - `"4g"` - - `image_url: optional string` + - `"16g"` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `"64g"` - - `prompt_cache_breakpoint: optional object { mode }` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + Network access policy for the container. - - `mode: "explicit"` + - `BetaContainerNetworkPolicyDisabled object { type }` - The breakpoint mode. Always `explicit`. + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `"explicit"` + - `type: "code_interpreter"` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + The type of the code interpreter tool. Always `code_interpreter`. - A file input to the model. + - `"code_interpreter"` - - `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`. + - `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"` - - `"low"` + - `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"` - - `file_data: optional string` + - `"low"` - The content of the file to be sent to the model. + - `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` - The ID of the file to be sent to the model. + File ID for the mask image. - - `file_url: optional string` + - `image_url: optional string` - The URL of the file to be sent to the model. + Base64-encoded mask image. - - `filename: optional string` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - The name of the file to be sent to the model. + The image generation model to use. Default: `gpt-image-1`. - - `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. + - `"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`. + - `"gpt-image-1"` - - `"explicit"` + - `"gpt-image-1-mini"` - - `role: "user" or "assistant" or "system" or "developer"` + - `"gpt-image-1.5"` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + - `moderation: optional "auto" or "low"` - - `"user"` + Moderation level for the generated image. Default: `auto`. - - `"assistant"` + - `"auto"` - - `"system"` + - `"low"` - - `"developer"` + - `output_compression: optional number` - - `phase: optional "commentary" or "final_answer"` + Compression level for the output image. Default: 100. - 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. + - `output_format: optional "png" or "webp" or "jpeg"` - - `"commentary"` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `"final_answer"` + - `"png"` - - `type: optional "message"` + - `"webp"` - The type of the message input. Always `message`. + - `"jpeg"` - - `"message"` + - `partial_images: optional number` - - `Message object { content, role, agent, 2 more }` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - 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. + - `quality: optional "low" or "medium" or "high" or "auto"` - - `content: BetaResponseInputMessageContentList` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - A list of one or many input items to the model, containing different content - types. + - `"low"` - - `role: "user" or "system" or "developer"` + - `"medium"` - The role of the message input. One of `user`, `system`, or `developer`. + - `"high"` - - `"user"` + - `"auto"` - - `"system"` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `"developer"` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `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"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"1024x1536"` - The status of 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. - - `type: optional "message"` + - `type: "local_shell"` - The type of the message input. Always set to `message`. + The type of the local shell tool. Always `local_shell`. - - `"message"` + - `"local_shell"` - - `BetaResponseOutputMessage object { id, content, role, 4 more }` + - `Shell object { type, allowed_callers, environment }` - An output message from the model. + A tool that allows the model to execute shell commands. - - `id: string` + - `type: "shell"` - The unique ID of the output message. + The type of the shell tool. Always `shell`. - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + - `"shell"` - The content of the output message. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `BetaResponseOutputText object { annotations, text, type, logprobs }` + The tool invocation context(s). - A text output from the model. + - `"direct"` - - `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 }` + - `"programmatic"` - The annotations of the text output. + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - `FileCitation object { file_id, filename, index, type }` + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - A citation to a file. + - `BetaLocalEnvironment object { type, skills }` - - `file_id: string` + - `BetaContainerReference object { container_id, type }` - The ID of the file. + - `Custom object { name, type, allowed_callers, 3 more }` - - `filename: string` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - The filename of the file cited. + - `name: string` - - `index: number` + The name of the custom tool, used to identify it in tool calls. - The index of the file in the list of files. + - `type: "custom"` - - `type: "file_citation"` + The type of the custom tool. Always `custom`. - The type of the file citation. Always `file_citation`. + - `"custom"` - - `"file_citation"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `URLCitation object { end_index, start_index, title, 2 more }` + The tool invocation context(s). - A citation for a web resource used to generate a model response. + - `"direct"` - - `end_index: number` + - `"programmatic"` - The index of the last character of the URL citation in the message. + - `defer_loading: optional boolean` - - `start_index: number` + Whether this tool should be deferred and discovered via tool search. - The index of the first character of the URL citation in the message. + - `description: optional string` - - `title: string` + Optional description of the custom tool, used to provide more context. - The title of the web resource. + - `format: optional object { type } or object { definition, syntax, type }` - - `type: "url_citation"` + The input format for the custom tool. Default is unconstrained text. - The type of the URL citation. Always `url_citation`. + - `Text object { type }` - - `"url_citation"` + Unconstrained free-form text. - - `url: string` + - `type: "text"` - The URL of the web resource. + Unconstrained text format. Always `text`. - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + - `"text"` - A citation for a container file used to generate a model response. + - `Grammar object { definition, syntax, type }` - - `container_id: string` + A grammar defined by the user. - The ID of the container file. + - `definition: string` - - `end_index: number` + The grammar definition. - The index of the last character of the container file 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 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 container file citation in the message. + - `"grammar"` - - `type: "container_file_citation"` + - `Namespace object { description, name, tools, type }` - The type of the container file citation. Always `container_file_citation`. + Groups function/custom tools under a shared namespace. - - `"container_file_citation"` + - `description: string` - - `FilePath object { file_id, index, type }` + A description of the namespace shown to the model. - A path to a file. + - `name: string` - - `file_id: string` + The namespace name used in tool calls (for example, `crm`). - The ID of the file. + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - - `index: number` + The function/custom tools available inside this namespace. - The index of the file in the list of files. + - `Function object { name, type, allowed_callers, 5 more }` - - `type: "file_path"` + - `name: string` - The type of the file path. Always `file_path`. + - `type: "function"` - - `"file_path"` + - `"function"` - - `text: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The text output from the model. + The tool invocation context(s). - - `type: "output_text"` + - `"direct"` - The type of the output text. Always `output_text`. + - `"programmatic"` - - `"output_text"` + - `defer_loading: optional boolean` - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + Whether this function should be deferred and discovered via tool search. - - `token: string` + - `description: optional string` - - `bytes: array of number` + - `output_schema: optional map[unknown]` - - `logprob: number` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `top_logprobs: array of object { token, bytes, logprob }` + - `parameters: optional unknown` - - `token: string` + - `strict: optional boolean` - - `bytes: array of 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. - - `logprob: number` + - `Custom object { name, type, allowed_callers, 3 more }` - - `BetaResponseOutputRefusal object { refusal, type }` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - A refusal from the model. + - `name: string` - - `refusal: string` + The name of the custom tool, used to identify it in tool calls. - The refusal explanation from the model. + - `type: "custom"` - - `type: "refusal"` + The type of the custom tool. Always `custom`. - The type of the refusal. Always `refusal`. + - `"custom"` - - `"refusal"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `role: "assistant"` + The tool invocation context(s). - The role of the output message. Always `assistant`. + - `"direct"` - - `"assistant"` + - `"programmatic"` - - `status: "in_progress" or "completed" or "incomplete"` + - `defer_loading: optional boolean` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + Whether this tool should be deferred and discovered via tool search. - - `"in_progress"` + - `description: optional string` - - `"completed"` + Optional description of the custom tool, used to provide more context. - - `"incomplete"` + - `format: optional object { type } or object { definition, syntax, type }` - - `type: "message"` + The input format for the custom tool. Default is unconstrained text. - The type of the output message. Always `message`. + - `Text object { type }` - - `"message"` + 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 }` - - `phase: optional "commentary" or "final_answer"` + A grammar defined by the user. - 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. + - `definition: string` - - `"commentary"` + The grammar definition. - - `"final_answer"` + - `syntax: "lark" or "regex"` - - `FileSearchCall object { id, queries, status, 3 more }` + The syntax of the grammar definition. One of `lark` or `regex`. - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `"lark"` - - `id: string` + - `"regex"` - The unique ID of the file search tool call. + - `type: "grammar"` - - `queries: array of string` + Grammar format. Always `grammar`. - The queries used to search for files. + - `"grammar"` - - `status: "in_progress" or "searching" or "completed" or 2 more` + - `type: "namespace"` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + The type of the tool. Always `namespace`. - - `"in_progress"` + - `"namespace"` - - `"searching"` + - `ToolSearch object { type, description, execution, parameters }` - - `"completed"` + Hosted or BYOT tool search configuration for deferred tools. - - `"incomplete"` + - `type: "tool_search"` - - `"failed"` + The type of the tool. Always `tool_search`. - - `type: "file_search_call"` + - `"tool_search"` - The type of the file search tool call. Always `file_search_call`. + - `description: optional string` - - `"file_search_call"` + Description shown to the model for a client-executed tool search tool. - - `agent: optional object { agent_name }` + - `execution: optional "server" or "client"` - The agent that produced this item. + Whether tool search is executed by the server or by the client. - - `agent_name: string` + - `"server"` - The canonical name of the agent that produced this item. + - `"client"` - - `results: optional array of object { attributes, file_id, filename, 2 more }` + - `parameters: optional unknown` - The results of the file search tool call. + Parameter schema for a client-executed tool search tool. - - `attributes: optional map[string or number or boolean]` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - 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. + 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). - - `string` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `number` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `boolean` + - `"web_search_preview"` - - `file_id: optional string` + - `"web_search_preview_2025_03_11"` - The unique ID of the file. + - `search_content_types: optional array of "text" or "image"` - - `filename: optional string` + - `"text"` - The name of the file. + - `"image"` - - `score: optional number` + - `search_context_size: optional "low" or "medium" or "high"` - The relevance score of the file - a value between 0 and 1. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `text: optional string` + - `"low"` - The text that was retrieved from the file. + - `"medium"` - - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` + - `"high"` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + - `user_location: optional object { type, city, country, 2 more }` - - `id: string` + The user's location. - The unique ID of the computer call. + - `type: "approximate"` - - `call_id: string` + The type of location approximation. Always `approximate`. - An identifier used when responding to the tool call with output. + - `"approximate"` - - `pending_safety_checks: array of object { id, code, message }` + - `city: optional string` - The pending safety checks for the computer call. + Free text input for the city of the user, e.g. `San Francisco`. - - `id: string` + - `country: optional string` - The ID of the pending safety check. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `code: optional string` + - `region: optional string` - The type of the pending safety check. + Free text input for the region of the user, e.g. `California`. - - `message: optional string` + - `timezone: optional string` - Details about the pending safety check. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `status: "in_progress" or "completed" or "incomplete"` + - `ApplyPatch object { type, allowed_callers }` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Allows the assistant to create, delete, or update files using unified diffs. - - `"in_progress"` + - `type: "apply_patch"` - - `"completed"` + The type of the tool. Always `apply_patch`. - - `"incomplete"` + - `"apply_patch"` - - `type: "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. + - `type: "tool_search_output"` - - `Click object { button, type, x, 2 more }` + The type of the item. Always `tool_search_output`. - A click action. + - `"tool_search_output"` - - `button: "left" or "right" or "wheel" or 2 more` + - `agent: optional object { agent_name }` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + The agent that produced this item. - - `"left"` + - `agent_name: string` - - `"right"` + The canonical name of the agent that produced this item. - - `"wheel"` + - `created_by: optional string` - - `"back"` + The identifier of the actor that created the item. - - `"forward"` + - `AdditionalTools object { id, role, tools, 2 more }` - - `type: "click"` + - `id: string` - Specifies the event type. For a click action, this property is always `click`. + The unique ID of the additional tools item. - - `"click"` + - `role: "unknown" or "user" or "assistant" or 5 more` - - `x: number` + The role that provided the additional tools. - The x-coordinate where the click occurred. + - `"unknown"` - - `y: number` + - `"user"` - The y-coordinate where the click occurred. + - `"assistant"` - - `keys: optional array of string` + - `"system"` - The keys being held while clicking. + - `"critic"` - - `DoubleClick object { keys, type, x, y }` + - `"discriminator"` - A double click action. + - `"developer"` - - `keys: array of string` + - `"tool"` - The keys being held while double-clicking. + - `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: "double_click"` + The additional tool definitions made available at this item. - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `Function object { name, parameters, strict, 5 more }` - - `"double_click"` + 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). - - `x: number` + - `name: string` - The x-coordinate where the double click occurred. + The name of the function to call. - - `y: number` + - `parameters: map[unknown]` - The y-coordinate where the double click occurred. + A JSON schema object describing the parameters of the function. - - `Drag object { path, type, keys }` + - `strict: boolean` - A drag action. + Whether strict parameter validation is enforced for this function tool. - - `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 + The type of the function tool. Always `function`. - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `"function"` - - `x: number` + - `allowed_callers: optional array of "direct" or "programmatic"` - The x-coordinate. + The tool invocation context(s). - - `y: number` + - `"direct"` - The y-coordinate. + - `"programmatic"` - - `type: "drag"` + - `defer_loading: optional boolean` - Specifies the event type. For a drag action, this property is always set to `drag`. + Whether this function is deferred and loaded via tool search. - - `"drag"` + - `description: optional string` - - `keys: optional array of string` + A description of the function. Used by the model to determine whether or not to call the function. - The keys being held while dragging the mouse. + - `output_schema: optional map[unknown]` - - `Keypress object { keys, type }` + A JSON schema object describing the JSON value encoded in string outputs for this function. - A collection of keypresses the model would like to perform. + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - - `keys: array of 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 combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `type: "file_search"` - - `type: "keypress"` + The type of the file search tool. Always `file_search`. - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `"file_search"` - - `"keypress"` + - `vector_store_ids: array of string` - - `Move object { type, x, y, keys }` + The IDs of the vector stores to search. - A mouse move action. + - `filters: optional object { key, type, value } or object { filters, type }` - - `type: "move"` + A filter to apply. - Specifies the event type. For a move action, this property is always set to `move`. + - `ComparisonFilter object { key, type, value }` - - `"move"` + 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 to move to. + The key to compare against the value. - - `y: number` + - `type: "eq" or "ne" or "gt" or 5 more` - The y-coordinate to move to. + 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 moving the mouse. + - `"eq"` - - `Screenshot object { type }` + - `"ne"` - A screenshot action. + - `"gt"` - - `type: "screenshot"` + - `"gte"` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `"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` - - `"screenshot"` + - `number` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `CompoundFilter object { filters, type }` - A scroll action. + Combine multiple filters using `and` or `or`. - - `scroll_x: number` + - `filters: array of object { key, type, value } or unknown` - The horizontal scroll distance. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `scroll_y: number` + - `ComparisonFilter object { key, type, value }` - The vertical scroll distance. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `type: "scroll"` + - `key: string` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + The key to compare against the value. - - `"scroll"` + - `type: "eq" or "ne" or "gt" or 5 more` - - `x: number` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The x-coordinate where the scroll 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 - - `y: number` + - `"eq"` - The y-coordinate where the scroll occurred. + - `"ne"` - - `keys: optional array of string` + - `"gt"` - The keys being held while scrolling. + - `"gte"` - - `Type object { text, type }` + - `"lt"` - An action to type in text. + - `"lte"` - - `text: string` + - `"in"` - The text to type. + - `"nin"` - - `type: "type"` + - `value: string or number or boolean or array of string or number` - Specifies the event type. For a type action, this property is always set to `type`. + The value to compare against the attribute key; supports string, number, or boolean types. - - `"type"` + - `string` - - `Wait object { type }` + - `number` - A wait action. + - `boolean` - - `type: "wait"` + - `array of string or number` - Specifies the event type. For a wait action, this property is always set to `wait`. + - `string` - - `"wait"` + - `number` - - `actions: optional BetaComputerActionList` + - `unknown` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `type: "and" or "or"` - - `Click object { button, type, x, 2 more }` + Type of operation: `and` or `or`. - A click action. + - `"and"` - - `DoubleClick object { keys, type, x, y }` + - `"or"` - A double click action. + - `max_num_results: optional number` - - `Drag object { path, type, keys }` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - A drag action. + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `Keypress object { keys, type }` + Ranking options for search. - A collection of keypresses the model would like to perform. + - `hybrid_search: optional object { embedding_weight, text_weight }` - - `Move object { type, x, y, keys }` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - A mouse move action. + - `embedding_weight: number` - - `Screenshot object { type }` + The weight of the embedding in the reciprocal ranking fusion. - A screenshot action. + - `text_weight: number` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + The weight of the text in the reciprocal ranking fusion. - A scroll action. + - `ranker: optional "auto" or "default-2024-11-15"` - - `Type object { text, type }` + The ranker to use for the file search. - An action to type in text. + - `"auto"` - - `Wait object { type }` + - `"default-2024-11-15"` - A wait action. + - `score_threshold: optional number` - - `agent: optional object { agent_name }` + 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 agent that produced this item. + - `Computer object { type }` - - `agent_name: string` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The canonical name of the agent that produced this item. + - `type: "computer"` - - `ComputerCallOutput object { call_id, output, type, 4 more }` + The type of the computer tool. Always `computer`. - The output of a computer tool call. + - `"computer"` - - `call_id: string` + - `ComputerUsePreview object { display_height, display_width, environment, type }` - The ID of the computer tool call that produced the output. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `display_height: number` - A computer screenshot image used with the computer use tool. + The height of the computer display. - - `type: "computer_screenshot"` + - `display_width: number` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + The width of the computer display. - - `"computer_screenshot"` + - `environment: "windows" or "mac" or "linux" or 2 more` - - `file_id: optional string` + The type of computer environment to control. - The identifier of an uploaded file that contains the screenshot. + - `"windows"` - - `image_url: optional string` + - `"mac"` - The URL of the screenshot image. + - `"linux"` - - `type: "computer_call_output"` + - `"ubuntu"` - The type of the computer tool call output. Always `computer_call_output`. + - `"browser"` - - `"computer_call_output"` + - `type: "computer_use_preview"` - - `id: optional string` + The type of the computer use tool. Always `computer_use_preview`. - The ID of the computer tool call output. + - `"computer_use_preview"` - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `WebSearch object { type, filters, search_context_size, user_location }` - The safety checks reported by the API that have been acknowledged by the developer. + 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 ID of the pending safety check. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `code: optional string` + - `"web_search"` - The type of the pending safety check. + - `"web_search_2025_08_26"` - - `message: optional string` + - `filters: optional object { allowed_domains }` - Details about the pending safety check. + Filters for the search. - - `agent: optional object { agent_name }` + - `allowed_domains: optional array of string` - 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. - - `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"` - - `status: optional "in_progress" or "completed" or "incomplete"` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + - `"low"` - - `"in_progress"` + - `"medium"` - - `"completed"` + - `"high"` - - `"incomplete"` + - `user_location: optional object { city, country, region, 2 more }` - - `WebSearchCall object { id, action, status, 2 more }` + The approximate location of the user. - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `city: optional string` - - `id: string` + Free text input for the city of the user, e.g. `San Francisco`. - The unique ID of the web search tool call. + - `country: optional string` - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - 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). + - `region: optional string` - - `Search object { type, queries, query, sources }` + Free text input for the region of the user, e.g. `California`. - Action type "search" - Performs a web search query. + - `timezone: optional string` - - `type: "search"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The action type. + - `type: optional "approximate"` - - `"search"` + The type of location approximation. Always `approximate`. - - `queries: optional array of string` + - `"approximate"` - The search queries. + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `query: 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 search query. + - `server_label: string` - - `sources: optional array of object { type, url }` + A label for this MCP server, used to identify it in tool calls. - The sources used in the search. + - `type: "mcp"` - - `type: "url"` + The type of the MCP tool. Always `mcp`. - The type of source. Always `url`. + - `"mcp"` - - `"url"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `url: string` + The tool invocation context(s). - The URL of the source. + - `"direct"` - - `OpenPage object { type, url }` + - `"programmatic"` - Action type "open_page" - Opens a specific URL from search results. + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `type: "open_page"` + List of allowed tool names or a filter object. - The action type. + - `McpAllowedTools = array of string` - - `"open_page"` + A string array of allowed tool names - - `url: optional string` + - `McpToolFilter object { read_only, tool_names }` - The URL opened by the model. + A filter object to specify which tools are allowed. - - `FindInPage object { pattern, type, url }` + - `read_only: optional boolean` - Action type "find_in_page": Searches for a pattern within a loaded 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. - - `pattern: string` + - `tool_names: optional array of string` - The pattern or text to search for within the page. + List of allowed tool names. - - `type: "find_in_page"` + - `authorization: optional string` - The action 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. - - `"find_in_page"` + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `url: 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 URL of the page searched for the pattern. + Currently supported `connector_id` values are: - - `status: "in_progress" or "searching" or "completed" or "failed"` + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - The status of the web search tool call. + - `"connector_dropbox"` - - `"in_progress"` + - `"connector_gmail"` - - `"searching"` + - `"connector_googlecalendar"` - - `"completed"` + - `"connector_googledrive"` - - `"failed"` + - `"connector_microsoftteams"` - - `type: "web_search_call"` + - `"connector_outlookcalendar"` - The type of the web search tool call. Always `web_search_call`. + - `"connector_outlookemail"` - - `"web_search_call"` + - `"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. - - `FunctionCall object { arguments, call_id, name, 6 more }` + - `require_approval: optional object { always, never } or "always" or "never"` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + Specify which of the MCP server's tools require approval. - - `arguments: string` + - `McpToolApprovalFilter object { always, never }` - A JSON string of the arguments to pass to the function. + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `call_id: string` + - `always: optional object { read_only, tool_names }` - The unique ID of the function tool call generated by the model. + A filter object to specify which tools are allowed. - - `name: string` + - `read_only: optional boolean` - The name 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. - - `type: "function_call"` + - `tool_names: optional array of string` - The type of the function tool call. Always `function_call`. + List of allowed tool names. - - `"function_call"` + - `never: optional object { read_only, tool_names }` - - `id: optional string` + A filter object to specify which tools are allowed. - The unique ID of the function tool call. + - `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. + - `McpToolApprovalSetting = "always" or "never"` - - `caller: optional object { type } or object { caller_id, type }` + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - The execution context that produced this tool call. + - `"always"` - - `Direct object { type }` + - `"never"` - - `type: "direct"` + - `server_description: optional string` - - `"direct"` + Optional description of the MCP server, used to provide more context. - - `Program object { caller_id, type }` + - `server_url: optional string` - - `caller_id: string` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - The call ID of the program item that produced this tool call. + - `tunnel_id: optional string` - - `type: "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. - - `"program"` + - `CodeInterpreter object { container, type, allowed_callers }` - - `namespace: optional string` + A tool that runs Python code to help generate a response to a prompt. - The namespace of the function to run. + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `status: optional "in_progress" or "completed" or "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. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `string` - - `"in_progress"` + The container ID. - - `"completed"` + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - - `"incomplete"` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `FunctionCallOutput object { call_id, output, type, 4 more }` + - `type: "auto"` - The output of a function tool call. + Always `auto`. - - `call_id: string` + - `"auto"` - The unique ID of the function tool call generated by the model. + - `file_ids: optional array of string` - - `output: string or BetaResponseFunctionCallOutputItemList` + An optional list of uploaded files to make available to your code. - Text, image, or file output of the function tool call. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `string` + The memory limit for the code interpreter container. - A JSON string of the output of the function tool call. + - `"1g"` - - `BetaResponseFunctionCallOutputItemList = array of BetaResponseFunctionCallOutputItem` + - `"4g"` - An array of content outputs (text, image, file) for the function tool call. + - `"16g"` - - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` + - `"64g"` - A text input to the model. + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `text: string` + Network access policy for the container. - The text input to the model. + - `BetaContainerNetworkPolicyDisabled object { type }` - - `type: "input_text"` + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - The type of the input item. Always `input_text`. + - `type: "code_interpreter"` - - `"input_text"` + The type of the code interpreter tool. Always `code_interpreter`. - - `prompt_cache_breakpoint: optional object { mode }` + - `"code_interpreter"` - Marks the exact end of a reusable 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"` - - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` + - `ProgrammaticToolCalling object { type }` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `type: "programmatic_tool_calling"` - - `type: "input_image"` + The type of the tool. Always `programmatic_tool_calling`. - The type of the input item. Always `input_image`. + - `"programmatic_tool_calling"` - - `"input_image"` + - `ImageGeneration object { type, action, background, 9 more }` - - `detail: optional "low" or "high" or "auto" or "original"` + A tool that generates images using the GPT image models. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `type: "image_generation"` - - `"low"` + The type of the image generation tool. Always `image_generation`. - - `"high"` + - `"image_generation"` - - `"auto"` + - `action: optional "generate" or "edit" or "auto"` - - `"original"` + Whether to generate a new image or edit an existing image. Default: `auto`. - - `file_id: optional string` + - `"generate"` - The ID of the file to be sent to the model. + - `"edit"` - - `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. + - `background: optional "transparent" or "opaque" or "auto"` - - `prompt_cache_breakpoint: optional object { mode }` + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `"transparent"` - - `mode: "explicit"` + - `"opaque"` - The breakpoint mode. Always `explicit`. + - `"auto"` - - `"explicit"` + - `input_fidelity: optional "high" or "low"` - - `BetaResponseInputFileContent object { type, detail, file_data, 4 more }` + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - A file input to the model. + - `"high"` - - `type: "input_file"` + - `"low"` - The type of the input item. Always `input_file`. + - `input_image_mask: optional object { file_id, image_url }` - - `"input_file"` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `detail: optional "auto" or "low" or "high"` + - `file_id: optional 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`. + File ID for the mask image. - - `"auto"` + - `image_url: optional string` - - `"low"` + Base64-encoded mask image. - - `"high"` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `file_data: optional string` + The image generation model to use. Default: `gpt-image-1`. - The base64-encoded data of the file to be sent to the model. + - `string` - - `file_id: optional string` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - The ID of the file to be sent to the model. + The image generation model to use. Default: `gpt-image-1`. - - `file_url: optional string` + - `"gpt-image-1"` - The URL of the file to be sent to the model. + - `"gpt-image-1-mini"` - - `filename: optional string` + - `"gpt-image-1.5"` - The name of the file to be sent to the model. + - `moderation: optional "auto" or "low"` - - `prompt_cache_breakpoint: optional object { mode }` + Moderation level for the generated image. Default: `auto`. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `"auto"` - - `mode: "explicit"` + - `"low"` - The breakpoint mode. Always `explicit`. + - `output_compression: optional number` - - `"explicit"` + Compression level for the output image. Default: 100. - - `type: "function_call_output"` + - `output_format: optional "png" or "webp" or "jpeg"` - The type of the function tool call output. Always `function_call_output`. + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `"function_call_output"` + - `"png"` - - `id: optional string` + - `"webp"` - The unique ID of the function tool call output. Populated when this item is returned via API. + - `"jpeg"` - - `agent: optional object { agent_name }` + - `partial_images: optional number` - The agent that produced this item. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `agent_name: string` + - `quality: optional "low" or "medium" or "high" or "auto"` - The canonical name of the agent that produced this item. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `caller: optional object { type } or object { caller_id, type }` + - `"low"` - The execution context that produced this tool call. + - `"medium"` - - `Direct object { type }` + - `"high"` - - `type: "direct"` + - `"auto"` - The caller type. Always `direct`. + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `"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`. - - `Program object { caller_id, type }` + - `string` - - `caller_id: string` + - `"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"` + - `"1024x1024"` - The caller type. Always `program`. + - `"1024x1536"` - - `"program"` + - `"1536x1024"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"auto"` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + - `LocalShell object { type }` - - `"in_progress"` + A tool that allows the model to execute shell commands in a local environment. - - `"completed"` + - `type: "local_shell"` - - `"incomplete"` + The type of the local shell tool. Always `local_shell`. - - `AgentMessage object { author, content, recipient, 3 more }` + - `"local_shell"` - A message routed between agents. + - `Shell object { type, allowed_callers, environment }` - - `author: string` + A tool that allows the model to execute shell commands. - The sending agent identity. + - `type: "shell"` - - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` + The type of the shell tool. Always `shell`. - Plaintext, image, or encrypted content sent between agents. + - `"shell"` - - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` + - `allowed_callers: optional array of "direct" or "programmatic"` - A text input to the model. + The tool invocation context(s). - - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` + - `"direct"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `"programmatic"` - - `EncryptedContent object { encrypted_content, type }` + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - - `encrypted_content: string` + - `BetaLocalEnvironment object { type, skills }` - Opaque encrypted content. + - `BetaContainerReference object { container_id, type }` - - `type: "encrypted_content"` + - `Custom object { name, type, allowed_callers, 3 more }` - The type of the input item. Always `encrypted_content`. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `"encrypted_content"` + - `name: string` - - `recipient: string` + The name of the custom tool, used to identify it in tool calls. - The destination agent identity. + - `type: "custom"` - - `type: "agent_message"` + The type of the custom tool. Always `custom`. - The item type. Always `agent_message`. + - `"custom"` - - `"agent_message"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `id: optional string` + The tool invocation context(s). - The unique ID of this agent message item. + - `"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` - - `MultiAgentCall object { action, arguments, call_id, 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 was executed. + 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 }` - - `arguments: string` + A grammar defined by the user. - The action arguments as a JSON string. + - `definition: string` - - `call_id: string` + The grammar definition. - The unique ID linking this call to its output. + - `syntax: "lark" or "regex"` - - `type: "multi_agent_call"` + The syntax of the grammar definition. One of `lark` or `regex`. - The item type. Always `multi_agent_call`. + - `"lark"` - - `"multi_agent_call"` + - `"regex"` - - `id: optional string` + - `type: "grammar"` - The unique ID of this multi-agent call. + Grammar format. Always `grammar`. - - `agent: optional object { agent_name }` + - `"grammar"` - The agent that produced this item. + - `Namespace object { description, name, tools, type }` - - `agent_name: string` + Groups function/custom tools under a shared namespace. - The canonical name of the agent that produced this item. + - `description: string` - - `MultiAgentCallOutput object { action, call_id, output, 3 more }` + A description of the namespace shown to the model. - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `name: string` - The multi-agent action that produced this result. + The namespace name used in tool calls (for example, `crm`). - - `"spawn_agent"` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - - `"interrupt_agent"` + The function/custom tools available inside this namespace. - - `"list_agents"` + - `Function object { name, type, allowed_callers, 5 more }` - - `"send_message"` + - `name: string` - - `"followup_task"` + - `type: "function"` - - `"wait_agent"` + - `"function"` - - `call_id: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The unique ID of the multi-agent call. + The tool invocation context(s). - - `output: array of object { text, type, annotations }` + - `"direct"` - Text output returned by the multi-agent action. + - `"programmatic"` - - `text: string` + - `defer_loading: optional boolean` - The text content. + Whether this function should be deferred and discovered via tool search. - - `type: "output_text"` + - `description: optional string` - The content type. Always `output_text`. + - `output_schema: optional map[unknown]` - - `"output_text"` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `annotations: optional array of object { file_id, filename, index, type } or array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` + - `parameters: optional unknown` - Citations associated with the text content. + - `strict: optional boolean` - - `array of object { file_id, filename, index, 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. - - `file_id: string` + - `Custom object { name, type, allowed_callers, 3 more }` - The ID of the file. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `filename: string` + - `name: string` - The filename of the file cited. + The name of the custom tool, used to identify it in tool calls. - - `index: number` + - `type: "custom"` - The index of the file in the list of files. + The type of the custom tool. Always `custom`. - - `type: "file_citation"` + - `"custom"` - The citation type. Always `file_citation`. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"file_citation"` + The tool invocation context(s). - - `array of object { end_index, start_index, title, 2 more }` + - `"direct"` - - `end_index: number` + - `"programmatic"` - The index of the last character of the citation in the message. + - `defer_loading: optional boolean` - - `start_index: number` + Whether this tool should be deferred and discovered via tool search. - The index of the first character of the citation in the message. + - `description: optional string` - - `title: string` + Optional description of the custom tool, used to provide more context. - The title of the cited resource. + - `format: optional object { type } or object { definition, syntax, type }` - - `type: "url_citation"` + The input format for the custom tool. Default is unconstrained text. - The citation type. Always `url_citation`. + - `Text object { type }` - - `"url_citation"` + Unconstrained free-form text. - - `url: string` + - `type: "text"` - The URL of the cited resource. + Unconstrained text format. Always `text`. - - `array of object { container_id, end_index, file_id, 3 more }` + - `"text"` - - `container_id: string` + - `Grammar object { definition, syntax, type }` - The ID of the container. + A grammar defined by the user. - - `end_index: number` + - `definition: string` - The index of the last character of the citation in the message. + The grammar definition. - - `file_id: string` + - `syntax: "lark" or "regex"` - The ID of the container file. + The syntax of the grammar definition. One of `lark` or `regex`. - - `filename: string` + - `"lark"` - The filename of the container file cited. + - `"regex"` - - `start_index: number` + - `type: "grammar"` - The index of the first character of the citation in the message. + Grammar format. Always `grammar`. - - `type: "container_file_citation"` + - `"grammar"` - The citation type. Always `container_file_citation`. + - `type: "namespace"` - - `"container_file_citation"` + The type of the tool. Always `namespace`. - - `type: "multi_agent_call_output"` + - `"namespace"` - The item type. Always `multi_agent_call_output`. + - `ToolSearch object { type, description, execution, parameters }` - - `"multi_agent_call_output"` + Hosted or BYOT tool search configuration for deferred tools. - - `id: optional string` + - `type: "tool_search"` - The unique ID of this multi-agent call output. + 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"` - - `ToolSearchCall object { arguments, type, id, 4 more }` + Whether tool search is executed by the server or by the client. - - `arguments: unknown` + - `"server"` - The arguments supplied to the tool search call. + - `"client"` - - `type: "tool_search_call"` + - `parameters: optional unknown` - The item type. Always `tool_search_call`. + Parameter schema for a client-executed tool search tool. - - `"tool_search_call"` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - - `id: optional string` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - The unique ID of this tool search call. + - `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"` - - `call_id: optional string` + - `"text"` - The unique ID of the tool search call generated by the model. + - `"image"` - - `execution: optional "server" or "client"` + - `search_context_size: optional "low" or "medium" or "high"` - Whether tool search was executed by the server or by the 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. - - `"server"` + - `"low"` - - `"client"` + - `"medium"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"high"` - The status of the tool search call. + - `user_location: optional object { type, city, country, 2 more }` - - `"in_progress"` + The user's location. - - `"completed"` + - `type: "approximate"` - - `"incomplete"` + The type of location approximation. Always `approximate`. - - `ToolSearchOutput object { tools, type, id, 4 more }` + - `"approximate"` - - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` + - `city: optional string` - The loaded tool definitions returned by the tool search output. + Free text input for the city of the user, e.g. `San Francisco`. - - `Function object { name, parameters, strict, 5 more }` + - `country: 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 two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `name: string` + - `region: optional string` - The name of the function to call. + Free text input for the region of the user, e.g. `California`. - - `parameters: map[unknown]` + - `timezone: optional string` - A JSON schema object describing the parameters of the function. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `strict: boolean` + - `ApplyPatch object { type, allowed_callers }` - Whether strict parameter validation is enforced for this function tool. + Allows the assistant to create, delete, or update files using unified diffs. - - `type: "function"` + - `type: "apply_patch"` - The type of the function tool. Always `function`. + The type of the tool. Always `apply_patch`. - - `"function"` + - `"apply_patch"` - `allowed_callers: optional array of "direct" or "programmatic"` @@ -63596,1183 +64083,1172 @@ Compact a response - `"programmatic"` - - `defer_loading: optional boolean` + - `type: "additional_tools"` - Whether this function is deferred and loaded via tool search. + The type of the item. Always `additional_tools`. - - `description: optional string` + - `"additional_tools"` - 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](https://platform.openai.com/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](https://platform.openai.com/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](https://platform.openai.com/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. - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + - `path: string` - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + Path of the file to update. - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `type: "update_file"` - - `"transparent"` + Update an existing file with the provided diff. - - `"opaque"` + - `"update_file"` - - `"auto"` + - `status: "in_progress" or "completed"` - - `input_fidelity: optional "high" or "low"` + The status of the apply patch tool call. One of `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`. + - `"in_progress"` - - `"high"` + - `"completed"` - - `"low"` + - `type: "apply_patch_call"` - - `input_image_mask: optional object { file_id, image_url }` + The type of the item. Always `apply_patch_call`. - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `"apply_patch_call"` - - `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-2" or 3 more` + - `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. - - `string` + - `Direct object { type }` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `type: "direct"` - The image generation model to use. Default: `gpt-image-1`. + - `"direct"` - - `"gpt-image-1"` + - `Program object { caller_id, type }` - - `"gpt-image-1-mini"` + - `caller_id: string` - - `"gpt-image-2"` + The call ID of the program item that produced this tool call. - - `"gpt-image-2-2026-04-21"` + - `type: "program"` - - `"gpt-image-1.5"` + - `"program"` - - `"chatgpt-image-latest"` + - `created_by: optional string` - - `moderation: optional "auto" or "low"` + The ID of the entity that created this tool call. - Moderation level for the generated image. Default: `auto`. + - `ApplyPatchCallOutput object { id, call_id, status, 5 more }` - - `"auto"` + The output emitted by an apply patch tool call. - - `"low"` + - `id: string` - - `output_compression: optional number` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - Compression level for the output image. Default: 100. + - `call_id: string` - - `output_format: optional "png" or "webp" or "jpeg"` + The unique ID of the apply patch tool call generated by the model. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `status: "completed" or "failed"` - - `"png"` + The status of the apply patch tool call output. One of `completed` or `failed`. - - `"webp"` + - `"completed"` - - `"jpeg"` + - `"failed"` - - `partial_images: optional number` + - `type: "apply_patch_call_output"` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + The type of the item. Always `apply_patch_call_output`. - - `quality: optional "low" or "medium" or "high" or "auto"` + - `"apply_patch_call_output"` - 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"` + - `caller: optional object { type } or object { caller_id, type }` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + The execution context 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`. + - `Direct object { type }` - - `string` + - `type: "direct"` - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `"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`. + - `Program object { caller_id, type }` - - `"1024x1024"` + - `caller_id: string` - - `"1024x1536"` + The call ID of the program item that produced this tool call. - - `"1536x1024"` + - `type: "program"` - - `"auto"` + - `"program"` - - `LocalShell object { type }` + - `created_by: optional string` - A tool that allows the model to execute shell commands in a local environment. + The ID of the entity that created this tool call output. - - `type: "local_shell"` + - `output: optional string` - The type of the local shell tool. Always `local_shell`. + Optional textual output returned by the apply patch tool. - - `"local_shell"` + - `McpCall object { id, arguments, name, 7 more }` - - `Shell object { type, allowed_callers, environment }` + An invocation of a tool on an MCP server. - A tool that allows the model to execute shell commands. + - `id: string` - - `type: "shell"` + The unique ID of the tool call. - The type of the shell tool. Always `shell`. + - `arguments: string` - - `"shell"` + 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. - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + - `type: "mcp_call"` - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + The type of the item. Always `mcp_call`. - - `type: "container_auto"` + - `"mcp_call"` - 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"` + - `approval_request_id: optional string` - The memory limit for the container. + 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. - - `"1g"` + - `error: optional string` - - `"4g"` + The error from the tool call, if any. - - `"16g"` + - `output: optional string` - - `"64g"` + The output from the tool call. - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - Network access policy for the container. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `BetaContainerNetworkPolicyDisabled object { type }` + - `"in_progress"` - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `"completed"` - - `skills: optional array of BetaSkillReference or BetaInlineSkill` + - `"incomplete"` - An optional list of skills referenced by id or inline data. + - `"calling"` - - `BetaSkillReference object { skill_id, type, version }` + - `"failed"` - - `skill_id: string` + - `McpListTools object { id, server_label, tools, 3 more }` - The ID of the referenced skill. + A list of tools available on an MCP server. - - `type: "skill_reference"` + - `id: string` - References a skill created with the /v1/skills endpoint. + The unique ID of the list. - - `"skill_reference"` + - `server_label: string` - - `version: optional string` + The label of the MCP server. - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `tools: array of object { input_schema, name, annotations, description }` - - `BetaInlineSkill object { description, name, source, type }` + The tools available on the server. - - `description: string` + - `input_schema: unknown` - The description of the skill. + The JSON schema describing the tool's input. - `name: string` - The name of the skill. + The name of the tool. - - `source: BetaInlineSkillSource` + - `annotations: optional unknown` - Inline skill payload + Additional annotations about the tool. - - `data: string` + - `description: optional string` - Base64-encoded skill zip bundle. + The description of the tool. - - `media_type: "application/zip"` + - `type: "mcp_list_tools"` - The media type of the inline skill payload. Must be `application/zip`. + The type of the item. Always `mcp_list_tools`. - - `"application/zip"` + - `"mcp_list_tools"` - - `type: "base64"` + - `agent: optional object { agent_name }` - The type of the inline skill source. Must be `base64`. + The agent that produced this item. - - `"base64"` + - `agent_name: string` - - `type: "inline"` + The canonical name of the agent that produced this item. - Defines an inline skill for this request. + - `error: optional string` - - `"inline"` + Error message if the server could not list tools. - - `BetaLocalEnvironment object { type, skills }` + - `McpApprovalRequest object { id, arguments, name, 3 more }` - - `type: "local"` + A request for human approval of a tool invocation. - Use a local computer environment. + - `id: string` - - `"local"` + The unique ID of the approval request. - - `skills: optional array of BetaLocalSkill` + - `arguments: string` - An optional list of skills. + A JSON string of arguments for the tool. - - `description: string` + - `name: string` - The description of the skill. + The name of the tool to run. - - `name: string` + - `server_label: string` - The name of the skill. + The label of the MCP server making the request. - - `path: string` + - `type: "mcp_approval_request"` - The path to the directory containing the skill. + The type of the item. Always `mcp_approval_request`. - - `BetaContainerReference object { container_id, type }` + - `"mcp_approval_request"` - - `container_id: string` + - `agent: optional object { agent_name }` - The ID of the referenced container. + The agent that produced this item. - - `type: "container_reference"` + - `agent_name: string` - References a container created with the /v1/containers endpoint + The canonical name of the agent that produced this item. - - `"container_reference"` + - `McpApprovalResponse object { id, approval_request_id, approve, 3 more }` - - `Custom object { name, type, allowed_callers, 3 more }` + A response to an MCP approval request. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `id: string` - - `name: string` + The unique ID of the approval response - The name of the custom tool, used to identify it in tool calls. + - `approval_request_id: string` - - `type: "custom"` + The ID of the approval request being answered. - The type of the custom tool. Always `custom`. + - `approve: boolean` - - `"custom"` + Whether the request was approved. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `type: "mcp_approval_response"` - The tool invocation context(s). + The type of the item. Always `mcp_approval_response`. - - `"direct"` + - `"mcp_approval_response"` - - `"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. + - `reason: optional string` - - `format: optional object { type } or object { definition, syntax, type }` + Optional reason for the decision. - The input format for the custom tool. Default is unconstrained text. + - `CustomToolCall object { call_id, input, name, 5 more }` - - `Text object { type }` + A call to a custom tool created by the model. - Unconstrained free-form text. + - `call_id: string` - - `type: "text"` + An identifier used to map this custom tool call to a tool call output. - Unconstrained text format. Always `text`. + - `input: string` - - `"text"` + The input for the custom tool call generated by the model. - - `Grammar object { definition, syntax, type }` + - `name: string` - A grammar defined by the user. + The name of the custom tool being called. - - `definition: string` + - `type: "custom_tool_call"` - The grammar definition. + The type of the custom tool call. Always `custom_tool_call`. - - `syntax: "lark" or "regex"` + - `"custom_tool_call"` - The syntax of the grammar definition. One of `lark` or `regex`. + - `id: optional string` - - `"lark"` + The unique ID of the custom tool call in the OpenAI platform. - - `"regex"` + - `agent: optional object { agent_name }` - - `type: "grammar"` + The agent that produced this item. - Grammar format. Always `grammar`. + - `agent_name: string` - - `"grammar"` + The canonical name of the agent that produced this item. - - `Namespace object { description, name, tools, type }` + - `caller: optional object { type } or object { caller_id, type }` - Groups function/custom tools under a shared namespace. + The execution context that produced this tool call. - - `description: string` + - `Direct object { type }` - A description of the namespace shown to the model. + - `type: "direct"` - - `name: string` + - `"direct"` - The namespace name used in tool calls (for example, `crm`). + - `Program object { caller_id, type }` - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + - `caller_id: string` - The function/custom tools available inside this namespace. + The call ID of the program item that produced this tool call. - - `Function object { name, type, allowed_callers, 5 more }` + - `type: "program"` - - `name: string` + - `"program"` - - `type: "function"` + - `namespace: optional string` - - `"function"` + The namespace of the custom tool being called. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `CustomToolCallOutput object { id, call_id, output, 5 more }` - The tool invocation context(s). + - `id: string` - - `"direct"` + The unique ID of the custom tool call output item. - - `"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 should be deferred and discovered 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. - - `output_schema: optional map[unknown]` + - `StringOutput = string` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + A string of the output of the custom tool call. - - `parameters: optional unknown` + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `strict: optional boolean` + Text, image, or file output of the custom tool 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. + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `Custom object { name, type, allowed_callers, 3 more }` + A text input to the model. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/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. + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `type: "custom"` + A file input to the model. - The type of the custom tool. Always `custom`. + - `status: "in_progress" or "completed" or "incomplete"` - - `"custom"` + 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: "custom_tool_call_output"` - - `defer_loading: optional boolean` + The type of the custom tool call output. Always `custom_tool_call_output`. - Whether this tool should be deferred and discovered via tool search. + - `"custom_tool_call_output"` - - `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"` + The caller type. Always `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`. + The caller type. Always `program`. - - `"lark"` + - `"program"` - - `"regex"` + - `created_by: optional string` - - `type: "grammar"` + The identifier of the actor that created the item. - Grammar format. Always `grammar`. + - `parallel_tool_calls: boolean` - - `"grammar"` + Whether to allow the model to run tool calls in parallel. - - `type: "namespace"` + - `temperature: number` - The type of the tool. Always `namespace`. + 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. - - `"namespace"` + - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` - - `ToolSearch object { type, description, execution, parameters }` + 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. - Hosted or BYOT tool search configuration for deferred tools. + - `BetaToolChoiceOptions = "none" or "auto" or "required"` - - `type: "tool_search"` + Controls which (if any) tool is called by the model. - The type of the tool. Always `tool_search`. + `none` means the model will not call any tool and instead generates a message. - - `"tool_search"` + `auto` means the model can pick between generating a message or calling one or + more tools. - - `description: optional string` + `required` means the model must call one or more tools. - Description shown to the model for a client-executed tool search tool. + - `"none"` - - `execution: optional "server" or "client"` + - `"auto"` - Whether tool search is executed by the server or by the client. + - `"required"` - - `"server"` + - `BetaToolChoiceAllowed object { mode, tools, type }` - - `"client"` + Constrains the tools available to the model to a pre-defined set. - - `parameters: optional unknown` + - `mode: "auto" or "required"` - Parameter schema for a client-executed tool search tool. + Constrains the tools available to the model to a pre-defined set. - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + `auto` allows the model to pick from among the allowed tools and generate a + 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). + `required` requires the model to call one or more of the allowed tools. - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `"auto"` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `"required"` - - `"web_search_preview"` + - `tools: array of map[unknown]` - - `"web_search_preview_2025_03_11"` + A list of tool definitions that the model should be allowed to call. - - `search_content_types: optional array of "text" or "image"` + 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"` - - `search_context_size: optional "low" or "medium" or "high"` + Allowed tool configuration type. Always `allowed_tools`. - 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. + - `"allowed_tools"` - - `"low"` + - `BetaToolChoiceTypes object { type }` - - `"medium"` + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](/docs/guides/tools). - - `"high"` + - `type: "file_search" or "web_search_preview" or "computer" or 5 more` - - `user_location: optional object { type, city, country, 2 more }` + The type of hosted tool the model should to use. Learn more about + [built-in tools](/docs/guides/tools). - The user's location. + Allowed values are: - - `type: "approximate"` + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - The type of location approximation. Always `approximate`. + - `"file_search"` - - `"approximate"` + - `"web_search_preview"` - - `city: optional string` + - `"computer"` - Free text input for the city of the user, e.g. `San Francisco`. + - `"computer_use_preview"` - - `country: optional string` + - `"computer_use"` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `"web_search_preview_2025_03_11"` - - `region: optional string` + - `"image_generation"` - Free text input for the region of the user, e.g. `California`. + - `"code_interpreter"` - - `timezone: optional string` + - `BetaToolChoiceFunction object { name, type }` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + Use this option to force the model to call a specific function. - - `ApplyPatch object { type, allowed_callers }` + - `name: string` - Allows the assistant to create, delete, or update files using unified diffs. + The name of the function to call. - - `type: "apply_patch"` + - `type: "function"` - The type of the tool. Always `apply_patch`. + For function calling, the type is always `function`. - - `"apply_patch"` + - `"function"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `BetaToolChoiceMcp object { server_label, type, name }` - The tool invocation context(s). + Use this option to force the model to call a specific tool on a remote MCP server. - - `"direct"` + - `server_label: string` - - `"programmatic"` + The label of the MCP server to use. - - `type: "tool_search_output"` + - `type: "mcp"` - The item type. Always `tool_search_output`. + For MCP tools, the type is always `mcp`. - - `"tool_search_output"` + - `"mcp"` - - `id: optional string` + - `name: optional string` - The unique ID of this tool search output. + The name of the tool to call on the server. - - `agent: optional object { agent_name }` + - `BetaToolChoiceCustom object { name, type }` - The agent that produced this item. + Use this option to force the model to call a specific custom tool. - - `agent_name: string` + - `name: string` - The canonical name of the agent that produced this item. + The name of the custom tool to call. - - `call_id: optional string` + - `type: "custom"` - The unique ID of the tool search call generated by the model. + For custom tool calling, the type is always `custom`. - - `execution: optional "server" or "client"` + - `"custom"` - Whether tool search was executed by the server or by the client. + - `BetaSpecificProgrammaticToolCallingParam object { type }` - - `"server"` + - `type: "programmatic_tool_calling"` - - `"client"` + The tool to call. Always `programmatic_tool_calling`. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"programmatic_tool_calling"` - The status of the tool search output. + - `BetaToolChoiceApplyPatch object { type }` - - `"in_progress"` + Forces the model to call the apply_patch tool when executing a tool call. - - `"completed"` + - `type: "apply_patch"` - - `"incomplete"` + The tool to call. Always `apply_patch`. - - `AdditionalTools object { role, tools, type, 2 more }` + - `"apply_patch"` - - `role: "developer"` + - `BetaToolChoiceShell object { type }` - The role that provided the additional tools. Only `developer` is supported. + Forces the model to call the shell tool when a tool call is required. - - `"developer"` + - `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` - A list of additional tools 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 }` @@ -65035,7 +65511,7 @@ Compact a response - `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](https://platform.openai.com/docs/guides/tools-web-search). + [web search tool](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -65095,7 +65571,7 @@ Compact a response - `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](https://platform.openai.com/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -65147,7 +65623,7 @@ Compact a response 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -65339,19 +65815,8 @@ Compact a response - `background: optional "transparent" or "opaque" or "auto"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. - - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. - - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - `"transparent"` @@ -65380,13 +65845,13 @@ Compact a response Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `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-2" or 3 more` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` The image generation model to use. Default: `gpt-image-1`. @@ -65394,14 +65859,8 @@ Compact a response - `"gpt-image-1-mini"` - - `"gpt-image-2"` - - - `"gpt-image-2-2026-04-21"` - - `"gpt-image-1.5"` - - `"chatgpt-image-latest"` - - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -65498,7 +65957,7 @@ Compact a response - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -65612,7 +66071,7 @@ Compact a response - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -65780,1190 +66239,1109 @@ Compact a response - `"programmatic"` - - `type: "additional_tools"` - - The item type. Always `additional_tools`. - - - `"additional_tools"` + - `top_p: number` - - `id: 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 unique ID of this additional tools item. + We generally recommend altering this or `temperature` but not both. - - `agent: optional object { agent_name }` + - `background: optional boolean` - The agent that produced this item. + Whether to run the model response in the background. + [Learn more](/docs/guides/background). - - `agent_name: string` + - `completed_at: optional number` - The canonical name of the agent that produced this item. + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - - `Reasoning object { id, summary, type, 4 more }` + - `conversation: optional object { id }` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + 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 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 - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. - - - `status: optional "in_progress" or "completed" or "incomplete"` - - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `Compaction object { encrypted_content, type, id, agent }` - - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/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. + The unique ID of the conversation that this response was associated with. - - `agent: optional object { agent_name }` + - `max_output_tokens: optional number` - The agent that produced this item. + 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). - - `agent_name: string` + - `max_tool_calls: optional number` - The canonical name of the agent that produced this item. + 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. - - `ImageGenerationCall object { id, result, status, 2 more }` + - `moderation: optional object { input, output }` - An image generation request made by the model. + Moderation results for the response input and output, if moderated completions were requested. - - `id: string` + - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` - The unique ID of the image generation call. + Moderation for the response input. - - `result: string` + - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` - The generated image encoded in base64. + A moderation result produced for the response input or output. - - `status: "in_progress" or "completed" or "generating" or "failed"` + - `categories: map[boolean]` - The status of the image generation call. + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `"in_progress"` + - `category_applied_input_types: map[array of "text" or "image"]` - - `"completed"` + Which modalities of input are reflected by the score for each category. - - `"generating"` + - `"text"` - - `"failed"` + - `"image"` - - `type: "image_generation_call"` + - `category_scores: map[number]` - The type of the image generation call. Always `image_generation_call`. + A dictionary of moderation categories to scores. - - `"image_generation_call"` + - `flagged: boolean` - - `agent: optional object { agent_name }` + A boolean indicating whether the content was flagged by any category. - The agent that produced this item. + - `model: string` - - `agent_name: string` + The moderation model that produced this result. - The canonical name of the agent that produced this item. + - `type: "moderation_result"` - - `CodeInterpreterCall object { id, code, container_id, 4 more }` + The object type, which was always `moderation_result` for successful moderation results. - A tool call to run code. + - `"moderation_result"` - - `id: string` + - `Error object { code, message, type }` - The unique ID of the code interpreter tool call. + An error produced while attempting moderation for the response input or output. - `code: string` - The code to run, or null if not available. - - - `container_id: string` + The error code. - The ID of the container used to run the code. + - `message: string` - - `outputs: array of object { logs, type } or object { type, url }` + The error message. - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `type: "error"` - - `Logs object { logs, type }` + The object type, which was always `error` for moderation failures. - The logs output from the code interpreter. + - `"error"` - - `logs: string` + - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` - The logs output from the code interpreter. + Moderation for the response output. - - `type: "logs"` + - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` - The type of the output. Always `logs`. + A moderation result produced for the response input or output. - - `"logs"` + - `categories: map[boolean]` - - `Image object { type, url }` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - The image output from the code interpreter. + - `category_applied_input_types: map[array of "text" or "image"]` - - `type: "image"` + Which modalities of input are reflected by the score for each category. - The type of the output. Always `image`. + - `"text"` - `"image"` - - `url: string` - - The URL of the image output from the code interpreter. + - `category_scores: map[number]` - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + A dictionary of moderation categories to scores. - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `flagged: boolean` - - `"in_progress"` + A boolean indicating whether the content was flagged by any category. - - `"completed"` + - `model: string` - - `"incomplete"` + The moderation model that produced this result. - - `"interpreting"` + - `type: "moderation_result"` - - `"failed"` + The object type, which was always `moderation_result` for successful moderation results. - - `type: "code_interpreter_call"` + - `"moderation_result"` - The type of the code interpreter tool call. Always `code_interpreter_call`. + - `Error object { code, message, type }` - - `"code_interpreter_call"` + An error produced while attempting moderation for the response input or output. - - `agent: optional object { agent_name }` + - `code: string` - The agent that produced this item. + The error code. - - `agent_name: string` + - `message: string` - The canonical name of the agent that produced this item. + The error message. - - `LocalShellCall object { id, action, call_id, 3 more }` + - `type: "error"` - A tool call to run a command on the local shell. + The object type, which was always `error` for moderation failures. - - `id: string` + - `"error"` - The unique ID of the local shell call. + - `output_text: optional string` - - `action: object { command, env, type, 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. - Execute a shell command on the server. + - `previous_response_id: optional string` - - `command: array of 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 command to run. + - `prompt: optional BetaResponsePrompt` - - `env: map[string]` + Reference to a prompt template and its variables. + [Learn more](/docs/guides/text?api-mode=responses#reusable-prompts). - Environment variables to set for the command. + - `id: string` - - `type: "exec"` + The unique identifier of the prompt template to use. - The type of the local shell action. Always `exec`. + - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` - - `"exec"` + 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. - - `timeout_ms: optional number` + - `string` - Optional timeout in milliseconds for the command. + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `user: optional string` + A text input to the model. - Optional user to run the command as. + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `working_directory: optional string` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - Optional working directory to run the command in. + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `call_id: string` + A file input to the model. - The unique ID of the local shell tool call generated by the model. + - `version: optional string` - - `status: "in_progress" or "completed" or "incomplete"` + Optional version of the prompt template. - The status of the local shell call. + - `prompt_cache_key: optional string` - - `"in_progress"` + 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). - - `"completed"` + - `prompt_cache_options: optional object { mode, ttl }` - - `"incomplete"` + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - - `type: "local_shell_call"` + - `mode: "implicit" or "explicit"` - The type of the local shell call. Always `local_shell_call`. + Whether implicit prompt-cache breakpoints were enabled. - - `"local_shell_call"` + - `"implicit"` - - `agent: optional object { agent_name }` + - `"explicit"` - The agent that produced this item. + - `ttl: "30m"` - - `agent_name: string` + The minimum lifetime applied to each cache breakpoint. - The canonical name of the agent that produced this item. + - `"30m"` - - `LocalShellCallOutput object { id, output, type, 2 more }` + - `prompt_cache_retention: optional "in_memory" or "24h"` - The output of a local shell tool call. + Deprecated. Use `prompt_cache_options.ttl` instead. - - `id: 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. - The unique ID of the local shell tool call generated by the model. + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - - `output: 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 local shell tool call. + - `"in_memory"` - - `type: "local_shell_call_output"` + - `"24h"` - The type of the local shell tool call output. Always `local_shell_call_output`. + - `reasoning: optional object { context, effort, generate_summary, 2 more }` - - `"local_shell_call_output"` + **gpt-5 and o-series models only** - - `agent: optional object { agent_name }` + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - The agent that produced this item. + - `context: optional "auto" or "current_turn" or "all_turns"` - - `agent_name: string` + Controls which reasoning items are rendered back to the model on later turns. + When returned on a response, this is the effective reasoning context mode + used for the response. - The canonical name of the agent that produced this item. + - `"auto"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"current_turn"` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `"all_turns"` - - `"in_progress"` + - `effort: optional "none" or "minimal" or "low" or 4 more` - - `"completed"` + 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. - - `"incomplete"` + - `"none"` - - `ShellCall object { action, call_id, type, 5 more }` + - `"minimal"` - A tool representing a request to execute one or more shell commands. + - `"low"` - - `action: object { commands, max_output_length, timeout_ms }` + - `"medium"` - The shell commands and limits that describe how to run the tool call. + - `"high"` - - `commands: array of string` + - `"xhigh"` - Ordered shell commands for the execution environment to run. + - `"max"` - - `max_output_length: optional number` + - `generate_summary: optional "auto" or "concise" or "detailed"` - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + **Deprecated:** use `summary` instead. - - `timeout_ms: optional 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`. - Maximum wall-clock time in milliseconds to allow the shell commands to run. + - `"auto"` - - `call_id: string` + - `"concise"` - The unique ID of the shell tool call generated by the model. + - `"detailed"` - - `type: "shell_call"` + - `mode: optional string or "standard" or "pro"` - The type of the item. Always `shell_call`. + Controls the reasoning execution mode for the request. - - `"shell_call"` + When returned on a response, this is the effective execution mode. - - `id: optional string` + - `string` - The unique ID of the shell tool call. Populated when this item is returned via API. + - `"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"` - - `caller: optional object { type } or object { caller_id, type }` + - `summary: optional "auto" or "concise" or "detailed"` - The execution context that produced this tool 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`. - - `Direct object { type }` + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - - `type: "direct"` + - `"auto"` - The caller type. Always `direct`. + - `"concise"` - - `"direct"` + - `"detailed"` - - `Program object { caller_id, type }` + - `safety_identifier: optional string` - - `caller_id: 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 call ID of the program item that produced this tool call. + - `service_tier: optional "auto" or "default" or "flex" or 2 more` - - `type: "program"` + Specifies the processing type used for serving the request. - The caller type. Always `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'. - - `"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. - - `environment: optional BetaLocalEnvironment or BetaContainerReference` + - `"auto"` - The environment to execute the shell commands in. + - `"default"` - - `BetaLocalEnvironment object { type, skills }` + - `"flex"` - - `BetaContainerReference object { container_id, type }` + - `"scale"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"priority"` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `status: optional BetaResponseStatus` - - `"in_progress"` + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - `"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 }` + - `"failed"` - Indicates that the shell commands finished and returned an exit code. + - `"in_progress"` - - `exit_code: number` + - `"cancelled"` - The exit code returned by the shell process. + - `"queued"` - - `type: "exit"` + - `"incomplete"` - The outcome type. Always `exit`. + - `text: optional BetaResponseTextConfig` - - `"exit"` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - - `stderr: string` + - [Text inputs and outputs](/docs/guides/text) + - [Structured Outputs](/docs/guides/structured-outputs) - Captured stderr output for the shell call. + - `format: optional BetaResponseFormatTextConfig` - - `stdout: string` + An object specifying the format that the model must output. - Captured stdout output for the shell call. + Configuring `{ "type": "json_schema" }` enables Structured Outputs, + which ensures the model will match your supplied JSON schema. Learn more in the + [Structured Outputs guide](/docs/guides/structured-outputs). - - `type: "shell_call_output"` + The default format is `{ "type": "text" }` with no additional options. - The type of the item. Always `shell_call_output`. + **Not recommended for gpt-4o and newer models:** - - `"shell_call_output"` + 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. - - `id: optional string` + - `Text object { type }` - The unique ID of the shell tool call output. Populated when this item is returned via API. + Default response format. Used to generate text responses. - - `agent: optional object { agent_name }` + - `type: "text"` - The agent that produced this item. + The type of response format being defined. Always `text`. - - `agent_name: string` + - `"text"` - The canonical name of the agent that produced this item. + - `BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` - - `caller: optional object { type } or object { caller_id, type }` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - The execution context that produced this tool call. + - `name: string` - - `Direct 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: "direct"` + - `schema: map[unknown]` - The caller type. Always `direct`. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `"direct"` + - `type: "json_schema"` - - `Program object { caller_id, type }` + The type of response format being defined. Always `json_schema`. - - `caller_id: string` + - `"json_schema"` - The call ID of the program item that produced this tool call. + - `description: optional string` - - `type: "program"` + A description of what the response format is for, used by the model to + determine how to respond in the format. - The caller type. Always `program`. + - `strict: optional boolean` - - `"program"` + 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). - - `max_output_length: optional number` + - `JSONObject object { type }` - The maximum number of UTF-8 characters captured for this shell call's combined output. + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `type: "json_object"` - The status of the shell call output. + The type of response format being defined. Always `json_object`. - - `"in_progress"` + - `"json_object"` - - `"completed"` + - `verbosity: optional "low" or "medium" or "high"` - - `"incomplete"` + 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`. - - `ApplyPatchCall object { call_id, operation, status, 4 more }` + - `"low"` - A tool call representing a request to create, delete, or update files using diff patches. + - `"medium"` - - `call_id: string` + - `"high"` - The unique ID of the apply patch tool call generated by the model. + - `top_logprobs: optional number` - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. - The specific create, delete, or update instruction for the apply_patch tool call. + - `truncation: optional "auto" or "disabled"` - - `CreateFile object { diff, path, type }` + The truncation strategy to use for the model response. - Instruction for creating a new file via the apply_patch tool. + - `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. - - `diff: string` + - `"auto"` - Unified diff content to apply when creating the file. + - `"disabled"` - - `path: string` + - `usage: optional BetaResponseUsage` - Path of the file to create relative to the workspace root. + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - - `type: "create_file"` + - `input_tokens: number` - The operation type. Always `create_file`. + The number of input tokens. - - `"create_file"` + - `input_tokens_details: object { cache_write_tokens, cached_tokens }` - - `DeleteFile object { path, type }` + A detailed breakdown of the input tokens. - Instruction for deleting an existing file via the apply_patch tool. + - `cache_write_tokens: number` - - `path: string` + The number of input tokens that were written to the cache. - Path of the file to delete relative to the workspace root. + - `cached_tokens: number` - - `type: "delete_file"` + The number of tokens that were retrieved from the cache. + [More on prompt caching](/docs/guides/prompt-caching). - The operation type. Always `delete_file`. + - `output_tokens: number` - - `"delete_file"` + The number of output tokens. - - `UpdateFile object { diff, path, type }` + - `output_tokens_details: object { reasoning_tokens }` - Instruction for updating an existing file via the apply_patch tool. + A detailed breakdown of the output tokens. - - `diff: string` + - `reasoning_tokens: number` - Unified diff content to apply to the existing file. + The number of reasoning tokens. - - `path: string` + - `total_tokens: number` - Path of the file to update relative to the workspace root. + The total number of tokens used. - - `type: "update_file"` + - `user: optional string` - The operation type. Always `update_file`. + 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). - - `"update_file"` +### Beta Response Audio Delta Event - - `status: "in_progress" or "completed"` +- `BetaResponseAudioDeltaEvent object { delta, sequence_number, type, agent }` - The status of the apply patch tool call. One of `in_progress` or `completed`. + Emitted when there is a partial audio response. - - `"in_progress"` + - `delta: string` - - `"completed"` + A chunk of Base64 encoded response audio bytes. - - `type: "apply_patch_call"` + - `sequence_number: number` - The type of the item. Always `apply_patch_call`. + A sequence number for this chunk of the stream response. - - `"apply_patch_call"` + - `type: "response.audio.delta"` - - `id: optional string` + The type of the event. Always `response.audio.delta`. - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `"response.audio.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 }` - - 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. +### Beta Response Audio Done Event - - `caller: optional object { type } or object { caller_id, type }` +- `BetaResponseAudioDoneEvent object { sequence_number, type, agent }` - The execution context that produced this tool call. + Emitted when the audio response is complete. - - `Direct object { type }` + - `sequence_number: number` - - `type: "direct"` + The sequence number of the delta. - The caller type. Always `direct`. + - `type: "response.audio.done"` - - `"direct"` + The type of the event. Always `response.audio.done`. - - `Program object { caller_id, type }` + - `"response.audio.done"` - - `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 Response Audio Transcript Delta Event - - `output: optional string` +- `BetaResponseAudioTranscriptDeltaEvent object { delta, sequence_number, type, agent }` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + Emitted when there is a partial transcript of audio. - - `McpListTools object { id, server_label, tools, 3 more }` + - `delta: string` - A list of tools available on an MCP server. + The partial transcript of the audio response. - - `id: string` + - `sequence_number: number` - The unique ID of the list. + The sequence number of this event. - - `server_label: string` + - `type: "response.audio.transcript.delta"` - The label of the MCP server. + The type of the event. Always `response.audio.transcript.delta`. - - `tools: array of object { input_schema, name, annotations, description }` + - `"response.audio.transcript.delta"` - The tools available on the server. + - `agent: optional object { agent_name }` - - `input_schema: unknown` + The agent that owns this multi-agent streaming event. - The JSON schema describing the tool's input. + - `agent_name: string` - - `name: string` + The canonical name of the agent that produced this item. - The name of the tool. +### Beta Response Audio Transcript Done Event - - `annotations: optional unknown` +- `BetaResponseAudioTranscriptDoneEvent object { sequence_number, type, agent }` - Additional annotations about the tool. + Emitted when the full audio transcript is completed. - - `description: optional string` + - `sequence_number: number` - The description of the tool. + The sequence number of this event. - - `type: "mcp_list_tools"` + - `type: "response.audio.transcript.done"` - The type of the item. Always `mcp_list_tools`. + The type of the event. Always `response.audio.transcript.done`. - - `"mcp_list_tools"` + - `"response.audio.transcript.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. - - `error: optional string` - - Error message if the server could not list tools. +### Beta Response Code Interpreter Call Code Delta Event - - `McpApprovalRequest object { id, arguments, name, 3 more }` +- `BetaResponseCodeInterpreterCallCodeDeltaEvent object { delta, item_id, output_index, 3 more }` - A request for human approval of a tool invocation. + Emitted when a partial code snippet is streamed by the code interpreter. - - `id: string` + - `delta: string` - The unique ID of the approval request. + The partial code snippet being streamed by the code interpreter. - - `arguments: string` + - `item_id: string` - A JSON string of arguments for the tool. + The unique identifier of the code interpreter tool call item. - - `name: string` + - `output_index: number` - The name of the tool to run. + The index of the output item in the response for which the code is being streamed. - - `server_label: string` + - `sequence_number: number` - The label of the MCP server making the request. + The sequence number of this event, used to order streaming events. - - `type: "mcp_approval_request"` + - `type: "response.code_interpreter_call_code.delta"` - The type of the item. Always `mcp_approval_request`. + The type of the event. Always `response.code_interpreter_call_code.delta`. - - `"mcp_approval_request"` + - `"response.code_interpreter_call_code.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 { approval_request_id, approve, type, 3 more }` +### Beta Response Code Interpreter Call Code Done Event - A response to an MCP approval request. +- `BetaResponseCodeInterpreterCallCodeDoneEvent object { code, item_id, output_index, 3 more }` - - `approval_request_id: string` + Emitted when the code snippet is finalized by the code interpreter. - The ID of the approval request being answered. + - `code: string` - - `approve: boolean` + The final code snippet output by the code interpreter. - Whether the request was approved. + - `item_id: string` - - `type: "mcp_approval_response"` + The unique identifier of the code interpreter tool call item. - The type of the item. Always `mcp_approval_response`. + - `output_index: number` - - `"mcp_approval_response"` + The index of the output item in the response for which the code is finalized. - - `id: optional string` + - `sequence_number: number` - The unique ID of the approval response + The sequence number of this event, used to order streaming events. - - `agent: optional object { agent_name }` + - `type: "response.code_interpreter_call_code.done"` - The agent that produced this item. + The type of the event. Always `response.code_interpreter_call_code.done`. - - `agent_name: string` + - `"response.code_interpreter_call_code.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` - - `McpCall object { id, arguments, name, 7 more }` + The canonical name of the agent that produced this item. - An invocation of a tool on an MCP server. +### Beta Response Code Interpreter Call Completed Event - - `id: string` +- `BetaResponseCodeInterpreterCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` - The unique ID of the tool call. + Emitted when the code interpreter call is completed. - - `arguments: string` + - `item_id: string` - A JSON string of the arguments passed to the tool. + The unique identifier of the code interpreter tool call item. - - `name: string` + - `output_index: number` - The name of the tool that was run. + The index of the output item in the response for which the code interpreter call is completed. - - `server_label: string` + - `sequence_number: number` - The label of the MCP server running the tool. + The sequence number of this event, used to order streaming events. - - `type: "mcp_call"` + - `type: "response.code_interpreter_call.completed"` - The type of the item. Always `mcp_call`. + The type of the event. Always `response.code_interpreter_call.completed`. - - `"mcp_call"` + - `"response.code_interpreter_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. - - `approval_request_id: optional string` +### Beta Response Code Interpreter Call In Progress 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. +- `BetaResponseCodeInterpreterCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` - - `error: optional string` + Emitted when a code interpreter call is in progress. - The error from the tool call, if any. + - `item_id: string` - - `output: optional string` + The unique identifier of the code interpreter tool call item. - The output from the tool call. + - `output_index: number` - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + The index of the output item in the response for which the code interpreter call is in progress. - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `sequence_number: number` - - `"in_progress"` + The sequence number of this event, used to order streaming events. - - `"completed"` + - `type: "response.code_interpreter_call.in_progress"` - - `"incomplete"` + The type of the event. Always `response.code_interpreter_call.in_progress`. - - `"calling"` + - `"response.code_interpreter_call.in_progress"` - - `"failed"` + - `agent: optional object { agent_name }` - - `CustomToolCallOutput object { call_id, output, type, 3 more }` + The agent that owns this multi-agent streaming event. - The output of a custom tool call from your code, being sent back to the model. + - `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 Code Interpreter Call Interpreting Event - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` +- `BetaResponseCodeInterpreterCallInterpretingEvent 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 the code interpreter is actively interpreting the code snippet. - - `StringOutput = string` + - `item_id: string` - A string of the output of the custom tool call. + The unique identifier of the code interpreter tool call item. - - `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 for which the code interpreter is interpreting code. - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `sequence_number: number` - A text input to the model. + The sequence number of this event, used to order streaming events. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `type: "response.code_interpreter_call.interpreting"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The type of the event. Always `response.code_interpreter_call.interpreting`. - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `"response.code_interpreter_call.interpreting"` - A file input to the model. + - `agent: optional object { agent_name }` - - `type: "custom_tool_call_output"` + The agent that owns this multi-agent streaming event. - The type of the custom tool call output. Always `custom_tool_call_output`. + - `agent_name: string` - - `"custom_tool_call_output"` + The canonical name of the agent that produced this item. - - `id: optional string` +### Beta Response Completed Event - The unique ID of the custom tool call output in the OpenAI platform. +- `BetaResponseCompletedEvent object { response, sequence_number, type, agent }` - - `agent: optional object { agent_name }` + Emitted when the model response is complete. - The agent that produced this item. + - `response: BetaResponse` - - `agent_name: string` + Properties of the completed response. - The canonical name of the agent that produced this item. + - `id: string` - - `caller: optional object { type } or object { caller_id, type }` + Unique identifier for this Response. - The execution context that produced this tool call. + - `created_at: number` - - `Direct object { type }` + Unix timestamp (in seconds) of when this Response was created. - - `type: "direct"` + - `error: BetaResponseError` - The caller type. Always `direct`. + An error object returned when the model fails to generate a Response. - - `"direct"` + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 16 more` - - `Program object { caller_id, type }` + The error code for the response. - - `caller_id: string` + - `"server_error"` - The call ID of the program item that produced this tool call. + - `"rate_limit_exceeded"` - - `type: "program"` + - `"invalid_prompt"` - The caller type. Always `program`. + - `"bio_policy"` - - `"program"` + - `"vector_store_timeout"` - - `CustomToolCall object { call_id, input, name, 5 more }` + - `"invalid_image"` - A call to a custom tool created by the model. + - `"invalid_image_format"` - - `call_id: string` + - `"invalid_base64_image"` - An identifier used to map this custom tool call to a tool call output. + - `"invalid_image_url"` - - `input: string` + - `"image_too_large"` - The input for the custom tool call generated by the model. + - `"image_too_small"` - - `name: string` + - `"image_parse_error"` - The name of the custom tool being called. + - `"image_content_policy_violation"` - - `type: "custom_tool_call"` + - `"invalid_image_mode"` - The type of the custom tool call. Always `custom_tool_call`. + - `"image_file_too_large"` - - `"custom_tool_call"` + - `"unsupported_image_media_type"` - - `id: optional string` + - `"empty_image_file"` - The unique ID of the custom tool call in the OpenAI platform. + - `"failed_to_download_image"` - - `agent: optional object { agent_name }` + - `"image_file_not_found"` - The agent that produced this item. + - `message: string` - - `agent_name: string` + A human-readable description of the error. - The canonical name of the agent that produced this item. + - `incomplete_details: object { reason }` - - `caller: optional object { type } or object { caller_id, type }` + Details about why the response is incomplete. - The execution context that produced this tool call. + - `reason: optional "max_output_tokens" or "content_filter"` - - `Direct object { type }` + The reason why the response is incomplete. - - `type: "direct"` + - `"max_output_tokens"` - - `"direct"` + - `"content_filter"` - - `Program object { caller_id, type }` + - `instructions: string or array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` - - `caller_id: string` + A system (or developer) message inserted into the model's context. - The call ID of the program item that produced this tool 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. - - `type: "program"` + - `string` - - `"program"` + A text input to the model, equivalent to a text input with the + `developer` role. - - `namespace: optional string` + - `InputItemList = array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` - The namespace of the custom tool being called. + A list of one or many input items to the model, containing + different content types. - - `CompactionTrigger object { type, agent }` + - `BetaEasyInputMessage object { content, role, phase, type }` - Compacts the current context. Must be the final input 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. - - `type: "compaction_trigger"` + - `content: string or BetaResponseInputMessageContentList` - The type of the item. Always `compaction_trigger`. + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `"compaction_trigger"` + - `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 }` - - `ItemReference object { id, agent, type }` + A text input to the model. - An internal identifier for an item to reference. + - `text: string` - - `id: string` + The text input to the model. - The ID of the item to reference. + - `type: "input_text"` - - `agent: optional object { agent_name }` + The type of the input item. Always `input_text`. - The agent that produced this item. + - `"input_text"` - - `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. - - `type: optional "item_reference"` + - `mode: "explicit"` - The type of item to reference. Always `item_reference`. + The breakpoint mode. Always `explicit`. - - `"item_reference"` + - `"explicit"` - - `Program object { id, call_id, code, 3 more }` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `id: string` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - The unique ID of this program item. + - `detail: "low" or "high" or "auto" or "original"` - - `call_id: string` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The stable call ID of the program item. + - `"low"` - - `code: string` + - `"high"` - The JavaScript source executed by programmatic tool calling. + - `"auto"` - - `fingerprint: string` + - `"original"` - Opaque program replay fingerprint that must be round-tripped. + - `type: "input_image"` - - `type: "program"` + The type of the input item. Always `input_image`. - The item type. Always `program`. + - `"input_image"` - - `"program"` + - `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 }` - - `ProgramOutput object { id, call_id, result, 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. - - `id: string` + - `mode: "explicit"` - The unique ID of this program output item. + The breakpoint mode. Always `explicit`. - - `call_id: string` + - `"explicit"` - The call ID of the program item. + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `result: string` + A file input to the model. - The result produced by the program item. + - `type: "input_file"` - - `status: "completed" or "incomplete"` + The type of the input item. Always `input_file`. - The terminal status of the program output. + - `"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: "program_output"` + - `"auto"` - The item type. Always `program_output`. + - `"low"` - - `"program_output"` + - `"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. -- `instructions: optional string` + - `file_url: optional string` - 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. + The URL of the file to be sent to the model. -- `previous_response_id: optional string` + - `filename: optional string` - The unique ID of the previous response to the model. Use this to create multi-turn conversations. Learn more about [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + The name of the file to be sent to the model. -- `prompt_cache_key: optional string` + - `prompt_cache_breakpoint: optional object { mode }` - A key to use when reading from or writing to the prompt cache. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. -- `prompt_cache_options: optional object { mode, ttl }` + - `mode: "explicit"` - 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](https://platform.openai.com/docs/guides/prompt-caching) for current details. + The breakpoint mode. Always `explicit`. - - `mode: optional "implicit" or "explicit"` + - `"explicit"` - 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. + - `role: "user" or "assistant" or "system" or "developer"` - - `"implicit"` + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - - `"explicit"` + - `"user"` - - `ttl: optional "30m"` + - `"assistant"` - 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. + - `"system"` - - `"30m"` + - `"developer"` -- `prompt_cache_retention: optional "in_memory" or "24h"` + - `phase: optional "commentary" or "final_answer"` - How long to retain a prompt cache entry created by this request. + 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. - - `"in_memory"` + - `"commentary"` - - `"24h"` + - `"final_answer"` -- `service_tier: optional "auto" or "default" or "flex" or "priority"` + - `type: optional "message"` - The service tier to use for this request. + The type of the message input. Always `message`. - - `"auto"` + - `"message"` - - `"default"` + - `Message object { content, role, agent, 2 more }` - - `"flex"` + 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. - - `"priority"` + - `content: BetaResponseInputMessageContentList` -### Returns + A list of one or many input items to the model, containing different content + types. -- `BetaCompactedResponse object { id, created_at, object, 2 more }` + - `role: "user" or "system" or "developer"` - - `id: string` + The role of the message input. One of `user`, `system`, or `developer`. - The unique identifier for the compacted response. + - `"user"` - - `created_at: number` + - `"system"` - Unix timestamp (in seconds) when the compacted conversation was created. + - `"developer"` - - `object: "response.compaction"` + - `agent: optional object { agent_name }` - The object type. Always `response.compaction`. + The agent that produced this item. - - `"response.compaction"` + - `agent_name: string` - - `output: array of BetaResponseOutputItem` + 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"` - The compacted list of output items. This is a list of all user messages, followed by a single compaction item. + - `type: optional "message"` + + The type of the message input. Always set to `message`. + + - `"message"` - `BetaResponseOutputMessage object { id, content, role, 4 more }` @@ -66977,7 +67355,7 @@ Compact a response The content of the output message. - - `BetaResponseOutputText object { annotations, text, type, logprobs }` + - `BetaResponseOutputText object { annotations, logprobs, text, type }` A text output from the model. @@ -67081,17 +67459,7 @@ Compact a response - `"file_path"` - - `text: string` - - The text output from the model. - - - `type: "output_text"` - - The type of the output text. Always `output_text`. - - - `"output_text"` - - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - `token: string` @@ -67107,6 +67475,16 @@ Compact a response - `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. @@ -67165,7 +67543,7 @@ Compact a response - `FileSearchCall object { id, queries, status, 3 more }` The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + [file search guide](/docs/guides/tools-file-search) for more information. - `id: string` @@ -67238,66 +67616,36 @@ Compact a response 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](https://platform.openai.com/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. @@ -67308,371 +67656,308 @@ Compact a response - `"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](https://platform.openai.com/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, text, type, logprobs }` + 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](https://platform.openai.com/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 }` @@ -67682,68 +67967,20 @@ Compact a response 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. - - - `text: string` - - The text output from the model. - - - `type: "output_text"` - - The type of the output text. Always `output_text`. - - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` - - - `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 }` The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + [web search guide](/docs/guides/tools-web-search) for more information. - `id: string` @@ -67844,360 +68081,349 @@ Compact a response 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](https://platform.openai.com/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 }` @@ -68207,138 +68433,127 @@ Compact a response 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](https://platform.openai.com/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 array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` - - `text: string` + Citations associated with the text content. - The reasoning text from the model. + - `array of 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 - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `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"` + - `array of 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"` + - `array of 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 }` @@ -68348,44 +68563,22 @@ Compact a response 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. @@ -68394,21 +68587,11 @@ Compact a response 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. @@ -68416,9 +68599,9 @@ Compact a response - `"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"` @@ -68426,9 +68609,11 @@ Compact a response - `"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 }` @@ -68691,7 +68876,7 @@ Compact a response - `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](https://platform.openai.com/docs/guides/tools-web-search). + [web search tool](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -68751,7 +68936,7 @@ Compact a response - `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](https://platform.openai.com/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -68803,7 +68988,7 @@ Compact a response 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -69027,19 +69212,8 @@ Compact a response - `background: optional "transparent" or "opaque" or "auto"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. - - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. - - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - `"transparent"` @@ -69068,13 +69242,13 @@ Compact a response Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `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-2" or 3 more` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` The image generation model to use. Default: `gpt-image-1`. @@ -69082,14 +69256,8 @@ Compact a response - `"gpt-image-1-mini"` - - `"gpt-image-2"` - - - `"gpt-image-2-2026-04-21"` - - `"gpt-image-1.5"` - - `"chatgpt-image-latest"` - - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -69304,7 +69472,7 @@ Compact a response - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -69418,7 +69586,7 @@ Compact a response - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -69588,10 +69756,14 @@ Compact a response - `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. @@ -69600,39 +69772,39 @@ Compact a response 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 }` @@ -69895,7 +70067,7 @@ Compact a response - `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](https://platform.openai.com/docs/guides/tools-web-search). + [web search tool](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -69955,7 +70127,7 @@ Compact a response - `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](https://platform.openai.com/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -70007,7 +70179,7 @@ Compact a response 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -70199,19 +70371,8 @@ Compact a response - `background: optional "transparent" or "opaque" or "auto"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. - - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. - - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - `"transparent"` @@ -70240,13 +70401,13 @@ Compact a response Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `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-2" or 3 more` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` The image generation model to use. Default: `gpt-image-1`. @@ -70254,14 +70415,8 @@ Compact a response - `"gpt-image-1-mini"` - - `"gpt-image-2"` - - - `"gpt-image-2-2026-04-21"` - - `"gpt-image-1.5"` - - `"chatgpt-image-latest"` - - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -70358,7 +70513,7 @@ Compact a response - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -70472,7 +70627,7 @@ Compact a response - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -70620,51 +70775,120 @@ Compact a response - `timezone: optional string` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + 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"` - - `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"` + - `content: optional array of object { text, type }` - - `allowed_callers: optional array of "direct" or "programmatic"` + Reasoning text content. - The tool invocation context(s). + - `text: string` - - `"direct"` + The reasoning text from the model. - - `"programmatic"` + - `type: "reasoning_text"` - - `type: "additional_tools"` + The type of the reasoning text. Always `reasoning_text`. - The type of the item. Always `additional_tools`. + - `"reasoning_text"` - - `"additional_tools"` + - `encrypted_content: optional string` - - `agent: optional object { agent_name }` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - 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"` - - `Compaction object { id, encrypted_content, type, 2 more }` + - `"completed"` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `"incomplete"` - - `id: string` + - `Compaction object { encrypted_content, type, id, agent }` - The unique ID of the compaction item. + 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"` @@ -70672,6 +70896,10 @@ Compact a response - `"compaction"` + - `id: optional string` + + The ID of the compaction item. + - `agent: optional object { agent_name }` The agent that produced this item. @@ -70680,10 +70908,6 @@ Compact a response 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. @@ -70901,13 +71125,9 @@ Compact a response - `"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 }` @@ -70915,60 +71135,30 @@ Compact a response - `commands: array of string` - - `max_output_length: number` + Ordered shell commands for the execution environment to run. - Optional maximum number of characters to return from each command. + - `max_output_length: optional number` - - `timeout_ms: number` + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - Optional timeout in milliseconds for the commands. + - `timeout_ms: optional number` + + Maximum wall-clock time in milliseconds to allow the shell commands to run. - `call_id: string` The unique ID of the shell tool call generated by the model. - - `environment: 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. @@ -70985,6 +71175,8 @@ Compact a response - `type: "direct"` + The caller type. Always `direct`. + - `"direct"` - `Program object { caller_id, type }` @@ -70995,35 +71187,43 @@ Compact a response - `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 }` @@ -71041,7 +71241,7 @@ Compact a response - `exit_code: number` - Exit code from the shell process. + The exit code returned by the shell process. - `type: "exit"` @@ -71051,32 +71251,22 @@ Compact a response - `stderr: string` - The standard error output that was captured. + Captured stderr output for the shell call. - `stdout: string` - The standard output that was captured. - - - `created_by: optional string` - - The identifier of the actor that created the item. - - - `status: "in_progress" or "completed" or "incomplete"` - - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` + Captured stdout output for the shell call. - `type: "shell_call_output"` - The type of the shell call output. Always `shell_call_output`. + The type of the item. Always `shell_call_output`. - `"shell_call_output"` + - `id: optional string` + + The unique ID of the shell tool call output. Populated when this item is returned via API. + - `agent: optional object { agent_name }` The agent that produced this item. @@ -71093,6 +71283,8 @@ Compact a response - `type: "direct"` + The caller type. Always `direct`. + - `"direct"` - `Program object { caller_id, type }` @@ -71103,19 +71295,27 @@ Compact a response - `type: "program"` + The caller type. Always `program`. + - `"program"` - - `created_by: optional string` + - `max_output_length: optional number` - The identifier of the actor that created the item. + The maximum number of UTF-8 characters captured for this shell call's combined output. - - `ApplyPatchCall object { id, call_id, operation, 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` @@ -71123,55 +71323,55 @@ Compact a response - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + The specific create, delete, or update instruction for the apply_patch tool call. - `CreateFile object { diff, path, type }` - Instruction describing how to create a file via the apply_patch tool. + Instruction for creating a new file via the apply_patch tool. - `diff: string` - Diff to apply. + Unified diff content to apply when creating the file. - `path: string` - Path of the file to create. + Path of the file to create relative to the workspace root. - `type: "create_file"` - Create a new file with the provided diff. + The operation type. Always `create_file`. - `"create_file"` - `DeleteFile object { path, type }` - Instruction describing how to delete a file via the apply_patch tool. + Instruction for deleting an existing file via the apply_patch tool. - `path: string` - Path of the file to delete. + Path of the file to delete relative to the workspace root. - `type: "delete_file"` - Delete the specified file. + The operation type. Always `delete_file`. - `"delete_file"` - `UpdateFile object { diff, path, type }` - Instruction describing how to update a file via the apply_patch tool. + Instruction for updating an existing file via the apply_patch tool. - `diff: string` - Diff to apply. + Unified diff content to apply to the existing file. - `path: string` - Path of the file to update. + Path of the file to update relative to the workspace root. - `type: "update_file"` - Update an existing file with the provided diff. + The operation type. Always `update_file`. - `"update_file"` @@ -71189,6 +71389,10 @@ Compact a response - `"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. @@ -71205,6 +71409,8 @@ Compact a response - `type: "direct"` + The caller type. Always `direct`. + - `"direct"` - `Program object { caller_id, type }` @@ -71215,19 +71421,13 @@ Compact a response - `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` @@ -71247,6 +71447,10 @@ Compact a response - `"apply_patch_call_output"` + - `id: optional string` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `agent: optional object { agent_name }` The agent that produced this item. @@ -71263,6 +71467,8 @@ Compact a response - `type: "direct"` + The caller type. Always `direct`. + - `"direct"` - `Program object { caller_id, type }` @@ -71273,76 +71479,13 @@ Compact a response - `type: "program"` - - `"program"` - - - `created_by: optional string` - - The ID of the entity that created this tool call output. - - - `output: optional string` - - Optional textual output returned by the apply patch tool. - - - `McpCall object { id, arguments, name, 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 caller type. Always `program`. - The error from the tool call, if any. + - `"program"` - `output: optional string` - The output from the tool call. - - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `"calling"` - - - `"failed"` + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - `McpListTools object { id, server_label, tools, 3 more }` @@ -71428,14 +71571,10 @@ Compact a response 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. @@ -71450,6 +71589,10 @@ Compact a 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. @@ -71462,31 +71605,31 @@ Compact a response Optional reason for the decision. - - `CustomToolCall object { call_id, input, name, 5 more }` + - `McpCall object { id, arguments, name, 7 more }` - A call to a custom tool created by the model. + An invocation of a tool on an MCP server. - - `call_id: string` + - `id: string` - An identifier used to map this custom tool call to a tool call output. + The unique ID of the tool call. - - `input: string` + - `arguments: string` - The input for the custom tool call generated by the model. + A JSON string of the arguments passed to the tool. - `name: string` - The name of the custom tool being called. + The name of the tool that was run. - - `type: "custom_tool_call"` + - `server_label: string` - The type of the custom tool call. Always `custom_tool_call`. + The label of the MCP server running the tool. - - `"custom_tool_call"` + - `type: "mcp_call"` - - `id: optional string` + The type of the item. Always `mcp_call`. - The unique ID of the custom tool call in the OpenAI platform. + - `"mcp_call"` - `agent: optional object { agent_name }` @@ -71496,35 +71639,36 @@ Compact a response The canonical name of the agent that produced this item. - - `caller: optional object { type } or object { caller_id, type }` + - `approval_request_id: optional string` - The execution context that produced this tool call. + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - - `Direct object { type }` + - `error: optional string` - - `type: "direct"` + The error from the tool call, if any. - - `"direct"` + - `output: optional string` - - `Program object { caller_id, type }` + The output from the tool call. - - `caller_id: string` + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - The call ID of the program item that produced this tool call. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `type: "program"` + - `"in_progress"` - - `"program"` + - `"completed"` - - `namespace: optional string` + - `"incomplete"` - The namespace of the custom tool being called. + - `"calling"` - - `CustomToolCallOutput object { id, call_id, output, 5 more }` + - `"failed"` - - `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` @@ -71549,29 +71693,22 @@ Compact a response - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + 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"` + - `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. @@ -71604,422 +71741,412 @@ Compact a response - `"program"` - - `created_by: optional string` + - `CustomToolCall object { call_id, input, name, 5 more }` - The identifier of the actor that created the item. + A call to a custom tool created by the model. - - `usage: BetaResponseUsage` + - `call_id: string` - Token accounting for the compaction pass, including cached, reasoning, and total tokens. + An identifier used to map this custom tool call to a tool call output. - - `input_tokens: number` + - `input: string` - The number of input tokens. + The input for the custom tool call generated by the model. - - `input_tokens_details: object { cache_write_tokens, cached_tokens }` + - `name: string` - A detailed breakdown of the input tokens. + The name of the custom tool being called. - - `cache_write_tokens: number` + - `type: "custom_tool_call"` - The number of input tokens that were written to the cache. + The type of the custom tool call. Always `custom_tool_call`. - - `cached_tokens: number` + - `"custom_tool_call"` - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + - `id: optional string` - - `output_tokens: number` + The unique ID of the custom tool call in the OpenAI platform. - 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. + - `caller: optional object { type } or object { caller_id, type }` - - `total_tokens: number` + The execution context that produced this tool call. - The total number of tokens used. + - `Direct object { type }` -### Example + - `type: "direct"` -```http -curl https://api.openai.com/v1/responses/compact \ - -H 'Content-Type: application/json' \ - -H 'OpenAI-Beta: assistants=v2' \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -d '{ - "model": "gpt-5.6-sol", - "previous_response_id": "resp_123" - }' -``` + - `"direct"` -#### Response + - `Program object { caller_id, type }` -```json -{ - "id": "id", - "created_at": 0, - "object": "response.compaction", - "output": [ - { - "id": "id", - "content": [ - { - "annotations": [ - { - "file_id": "file_id", - "filename": "filename", - "index": 0, - "type": "file_citation" - } - ], - "text": "text", - "type": "output_text", - "logprobs": [ - { - "token": "token", - "bytes": [ - 0 - ], - "logprob": 0, - "top_logprobs": [ - { - "token": "token", - "bytes": [ - 0 - ], - "logprob": 0 - } - ] - } - ] - } - ], - "role": "assistant", - "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 - } -} -``` + - `caller_id: string` -### Example + The call ID of the program item that produced this tool call. -```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" - } - ] - }' -``` + - `type: "program"` -#### Response + - `"program"` -```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 - }, - "output_tokens": 438, - "output_tokens_details": { - "reasoning_tokens": 64 - }, - "total_tokens": 577 - } -} -``` + - `namespace: optional string` -## Domain Types + The namespace of the custom tool being called. -### Beta Compacted Response + - `CompactionTrigger object { type, agent }` -- `BetaCompactedResponse object { id, created_at, object, 2 more }` + 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 unique identifier for the compacted response. + The ID of the item to reference. - - `created_at: number` + - `agent: optional object { agent_name }` - Unix timestamp (in seconds) when the compacted conversation was created. + The agent that produced this item. - - `object: "response.compaction"` + - `agent_name: string` - The object type. Always `response.compaction`. + The canonical name of the agent that produced this item. - - `"response.compaction"` + - `type: optional "item_reference"` - - `output: array of BetaResponseOutputItem` + The type of item to reference. Always `item_reference`. - The compacted list of output items. This is a list of all user messages, followed by a single compaction item. + - `"item_reference"` - - `BetaResponseOutputMessage object { id, content, role, 4 more }` + - `Program object { id, call_id, code, 3 more }` - An output message from the model. + - `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 }` - `id: string` - The unique ID of the output message. + The unique ID of this program output item. - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + - `call_id: string` - The content of the output message. + The call ID of the program item. - - `BetaResponseOutputText object { annotations, text, type, logprobs }` + - `result: string` - A text output from the model. + The result produced by 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 }` + - `status: "completed" or "incomplete"` - The annotations of the text output. + The terminal status of the program output. - - `FileCitation object { file_id, filename, index, type }` + - `"completed"` - A citation to a file. + - `"incomplete"` - - `file_id: string` + - `type: "program_output"` - The ID of the file. + The item type. Always `program_output`. - - `filename: string` + - `"program_output"` - The filename of the file cited. + - `agent: optional object { agent_name }` - - `index: number` + The agent that produced this item. - 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 type of the file citation. Always `file_citation`. + - `metadata: map[string]` - - `"file_citation"` + 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. - - `URLCitation object { end_index, start_index, title, 2 more }` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - A citation for a web resource used to generate a model response. + - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` - - `end_index: 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 index of the last character of the URL citation in the message. + - `"gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more` - - `start_index: 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 index of the first character of the URL citation in the message. + - `"gpt-5.6-sol"` - - `title: string` + - `"gpt-5.6-terra"` - The title of the web resource. + - `"gpt-5.6-luna"` - - `type: "url_citation"` + - `"gpt-5.4"` - The type of the URL citation. Always `url_citation`. + - `"gpt-5.4-mini"` - - `"url_citation"` + - `"gpt-5.4-nano"` - - `url: string` + - `"gpt-5.4-mini-2026-03-17"` - The URL of the web resource. + - `"gpt-5.4-nano-2026-03-17"` - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + - `"gpt-5.3-chat-latest"` - A citation for a container file used to generate a model response. + - `"gpt-5.2"` - - `container_id: string` + - `"gpt-5.2-2025-12-11"` - The ID of the container file. + - `"gpt-5.2-chat-latest"` - - `end_index: number` + - `"gpt-5.2-pro"` - The index of the last character of the container file citation in the message. + - `"gpt-5.2-pro-2025-12-11"` - - `file_id: string` + - `"gpt-5.1"` - The ID of the file. + - `"gpt-5.1-2025-11-13"` - - `filename: string` + - `"gpt-5.1-codex"` - The filename of the container file cited. + - `"gpt-5.1-mini"` - - `start_index: number` + - `"gpt-5.1-chat-latest"` - The index of the first character of the container file citation in the message. + - `"gpt-5"` - - `type: "container_file_citation"` + - `"gpt-5-mini"` - The type of the container file citation. Always `container_file_citation`. + - `"gpt-5-nano"` - - `"container_file_citation"` + - `"gpt-5-2025-08-07"` - - `FilePath object { file_id, index, type }` + - `"gpt-5-mini-2025-08-07"` - A path to a file. + - `"gpt-5-nano-2025-08-07"` - - `file_id: string` + - `"gpt-5-chat-latest"` - The ID of the file. + - `"gpt-4.1"` - - `index: number` + - `"gpt-4.1-mini"` - The index of the file in the list of files. + - `"gpt-4.1-nano"` - - `type: "file_path"` + - `"gpt-4.1-2025-04-14"` - The type of the file path. Always `file_path`. + - `"gpt-4.1-mini-2025-04-14"` - - `"file_path"` + - `"gpt-4.1-nano-2025-04-14"` - - `text: string` + - `"o4-mini"` - The text output from the model. + - `"o4-mini-2025-04-16"` - - `type: "output_text"` + - `"o3"` - The type of the output text. Always `output_text`. + - `"o3-2025-04-16"` - - `"output_text"` + - `"o3-mini"` - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + - `"o3-mini-2025-01-31"` - - `token: string` + - `"o1"` - - `bytes: array of number` + - `"o1-2024-12-17"` - - `logprob: number` + - `"o1-preview"` - - `top_logprobs: array of object { token, bytes, logprob }` + - `"o1-preview-2024-09-12"` - - `token: string` + - `"o1-mini"` - - `bytes: array of number` + - `"o1-mini-2024-09-12"` - - `logprob: number` + - `"gpt-4o"` - - `BetaResponseOutputRefusal object { refusal, type }` + - `"gpt-4o-2024-11-20"` - A refusal from the model. + - `"gpt-4o-2024-08-06"` - - `refusal: string` + - `"gpt-4o-2024-05-13"` - The refusal explanation from the model. + - `"gpt-4o-audio-preview"` - - `type: "refusal"` + - `"gpt-4o-audio-preview-2024-10-01"` - The type of the refusal. Always `refusal`. + - `"gpt-4o-audio-preview-2024-12-17"` - - `"refusal"` + - `"gpt-4o-audio-preview-2025-06-03"` - - `role: "assistant"` + - `"gpt-4o-mini-audio-preview"` - The role of the output message. Always `assistant`. + - `"gpt-4o-mini-audio-preview-2024-12-17"` - - `"assistant"` + - `"gpt-4o-search-preview"` - - `status: "in_progress" or "completed" or "incomplete"` + - `"gpt-4o-mini-search-preview"` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `"gpt-4o-search-preview-2025-03-11"` - - `"in_progress"` + - `"gpt-4o-mini-search-preview-2025-03-11"` - - `"completed"` + - `"chatgpt-4o-latest"` - - `"incomplete"` + - `"codex-mini-latest"` - - `type: "message"` + - `"gpt-4o-mini"` - The type of the output message. Always `message`. + - `"gpt-4o-mini-2024-07-18"` - - `"message"` + - `"gpt-4-turbo"` - - `agent: optional object { agent_name }` + - `"gpt-4-turbo-2024-04-09"` - The agent that produced this item. + - `"gpt-4-0125-preview"` - - `agent_name: string` + - `"gpt-4-turbo-preview"` - The canonical name of the agent that produced this item. + - `"gpt-4-1106-preview"` - - `phase: optional "commentary" or "final_answer"` + - `"gpt-4-vision-preview"` - 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. + - `"gpt-4"` - - `"commentary"` + - `"gpt-4-0314"` - - `"final_answer"` + - `"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"` + + - `"gpt-3.5-turbo-16k-0613"` + + - `"o1-pro"` + + - `"o1-pro-2025-03-19"` + + - `"o3-pro"` + + - `"o3-pro-2025-06-10"` + + - `"o3-deep-research"` + + - `"o3-deep-research-2025-06-26"` + + - `"o4-mini-deep-research"` + + - `"o4-mini-deep-research-2025-06-26"` + + - `"computer-use-preview"` + + - `"computer-use-preview-2025-03-11"` + + - `"gpt-5-codex"` + + - `"gpt-5-pro"` + + - `"gpt-5-pro-2025-10-06"` + + - `"gpt-5.1-codex-max"` + + - `string` + + - `object: "response"` + + 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 }` The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + [file search guide](/docs/guides/tools-file-search) for more information. - `id: string` @@ -72095,7 +72222,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `FunctionCall object { arguments, call_id, name, 6 more }` A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + [function calling guide](/docs/guides/function-calling) for more information. - `arguments: string` @@ -72189,112 +72316,14 @@ 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](https://platform.openai.com/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"` + 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"` - - 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 @@ -72366,7 +72395,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ A text input to the model. - - `BetaResponseOutputText object { annotations, text, type, logprobs }` + - `BetaResponseOutputText object { annotations, logprobs, text, type }` A text output from the model. @@ -72414,7 +72443,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + An image input to the model. Learn about [image inputs](/docs/guides/vision). - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` @@ -72570,6 +72599,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The annotations of the text output. + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + - `text: string` The text output from the model. @@ -72578,8 +72609,6 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The type of the output text. Always `output_text`. - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` - - `type: "multi_agent_call_output"` The type of the multi-agent result. Always `multi_agent_call_output`. @@ -72597,7 +72626,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `WebSearchCall object { id, action, status, 2 more }` The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + [web search guide](/docs/guides/tools-web-search) for more information. - `id: string` @@ -72701,7 +72730,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + [computer use guide](/docs/guides/tools-computer-use) for more information. - `id: string` @@ -72748,238 +72777,11 @@ 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. @@ -73002,21 +72804,6 @@ 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 @@ -73070,7 +72857,7 @@ curl -X POST https://api.openai.com/v1/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](https://platform.openai.com/docs/guides/conversation-state). + [managing context](/docs/guides/conversation-state). - `id: string` @@ -73545,7 +73332,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-web-search). + [web search tool](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -73605,7 +73392,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -73657,7 +73444,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -73803,40 +73590,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`. @@ -73881,19 +73636,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `background: optional "transparent" or "opaque" or "auto"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. - - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. - - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - `"transparent"` @@ -73922,13 +73666,13 @@ curl -X POST https://api.openai.com/v1/responses/compact \ Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `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-2" or 3 more` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` The image generation model to use. Default: `gpt-image-1`. @@ -73936,14 +73680,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"gpt-image-1-mini"` - - `"gpt-image-2"` - - - `"gpt-image-2-2026-04-21"` - - `"gpt-image-1.5"` - - `"chatgpt-image-latest"` - - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -74034,131 +73772,13 @@ 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](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -74272,7 +73892,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -74749,7 +74369,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-web-search). + [web search tool](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -74809,7 +74429,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -74861,7 +74481,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -75053,19 +74673,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `background: optional "transparent" or "opaque" or "auto"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. - - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. - - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - `"transparent"` @@ -75094,13 +74703,13 @@ curl -X POST https://api.openai.com/v1/responses/compact \ Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `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-2" or 3 more` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` The image generation model to use. Default: `gpt-image-1`. @@ -75108,14 +74717,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"gpt-image-1-mini"` - - `"gpt-image-2"` - - - `"gpt-image-2-2026-04-21"` - - `"gpt-image-1.5"` - - `"chatgpt-image-latest"` - - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -75212,7 +74815,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -75326,7 +74929,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -75510,7 +75113,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `Compaction object { id, encrypted_content, type, 2 more }` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). - `id: string` @@ -76403,7 +76006,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + An image input to the model. Learn about [image inputs](/docs/guides/vision). - `BetaResponseInputFile object { type, detail, file_data, 4 more }` @@ -76462,1008 +76065,1779 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The identifier of the actor that created the item. - - `usage: BetaResponseUsage` + - `parallel_tool_calls: boolean` - Token accounting for the compaction pass, including cached, reasoning, and total tokens. + Whether to allow the model to run tool calls in parallel. - - `input_tokens: number` + - `temperature: number` - The number of input 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. - - `input_tokens_details: object { cache_write_tokens, cached_tokens }` + - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` - A detailed breakdown of the input tokens. + 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. - - `cache_write_tokens: number` + - `BetaToolChoiceOptions = "none" or "auto" or "required"` - The number of input tokens that were written to the cache. + Controls which (if any) tool is called by the model. - - `cached_tokens: number` + `none` means the model will not call any tool and instead generates a message. - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + `auto` means the model can pick between generating a message or calling one or + more tools. - - `output_tokens: number` + `required` means the model must call one or more tools. - The number of output tokens. + - `"none"` - - `output_tokens_details: object { reasoning_tokens }` + - `"auto"` - A detailed breakdown of the output tokens. + - `"required"` - - `reasoning_tokens: number` + - `BetaToolChoiceAllowed object { mode, tools, type }` - The number of reasoning tokens. + Constrains the tools available to the model to a pre-defined set. - - `total_tokens: number` + - `mode: "auto" or "required"` - The total number of tokens used. + Constrains the tools available to the model to a pre-defined set. -### Beta Computer Action + `auto` allows the model to pick from among the allowed tools and generate a + message. -- `BetaComputerAction = object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` + `required` requires the model to call one or more of the allowed tools. - A click action. + - `"auto"` - - `Click object { button, type, x, 2 more }` + - `"required"` - A click action. + - `tools: array of map[unknown]` - - `button: "left" or "right" or "wheel" or 2 more` + A list of tool definitions that the model should be allowed to call. - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + For the Responses API, the list of tool definitions might look like: - - `"left"` + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - - `"right"` + - `type: "allowed_tools"` - - `"wheel"` + Allowed tool configuration type. Always `allowed_tools`. - - `"back"` + - `"allowed_tools"` - - `"forward"` + - `BetaToolChoiceTypes object { type }` - - `type: "click"` + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](/docs/guides/tools). - Specifies the event type. For a click action, this property is always `click`. + - `type: "file_search" or "web_search_preview" or "computer" or 5 more` - - `"click"` + The type of hosted tool the model should to use. Learn more about + [built-in tools](/docs/guides/tools). - - `x: number` + Allowed values are: - The x-coordinate where the click occurred. + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - - `y: number` + - `"file_search"` - The y-coordinate where the click occurred. + - `"web_search_preview"` - - `keys: optional array of string` + - `"computer"` - The keys being held while clicking. + - `"computer_use_preview"` - - `DoubleClick object { keys, type, x, y }` + - `"computer_use"` - A double click action. + - `"web_search_preview_2025_03_11"` - - `keys: array of string` + - `"image_generation"` - The keys being held while double-clicking. + - `"code_interpreter"` - - `type: "double_click"` + - `BetaToolChoiceFunction object { name, type }` - Specifies the event type. For a double click action, this property is always set to `double_click`. + Use this option to force the model to call a specific function. - - `"double_click"` + - `name: string` - - `x: number` + The name of the function to call. - The x-coordinate where the double click occurred. + - `type: "function"` - - `y: number` + For function calling, the type is always `function`. - The y-coordinate where the double click occurred. + - `"function"` - - `Drag object { path, type, keys }` + - `BetaToolChoiceMcp object { server_label, type, name }` - A drag action. + Use this option to force the model to call a specific tool on a remote MCP server. - - `path: array of object { x, y }` + - `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"` + + 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"` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `"low"` - - `x: number` + - `"medium"` - The x-coordinate. + - `"high"` - - `y: number` + - `"auto"` - The y-coordinate. + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `type: "drag"` + 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 event type. For a drag action, this property is always set to `drag`. + - `string` - - `"drag"` + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `keys: optional array of 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 keys being held while dragging the mouse. + - `"1024x1024"` - - `Keypress object { keys, type }` + - `"1024x1536"` - A collection of keypresses the model would like to perform. + - `"1536x1024"` - - `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. + - `LocalShell object { type }` - - `type: "keypress"` + A tool that allows the model to execute shell commands in a local environment. - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `type: "local_shell"` - - `"keypress"` + The type of the local shell tool. Always `local_shell`. - - `Move object { type, x, y, keys }` + - `"local_shell"` - A mouse move action. + - `Shell object { type, allowed_callers, environment }` - - `type: "move"` + A tool that allows the model to execute shell commands. - Specifies the event type. For a move action, this property is always set to `move`. + - `type: "shell"` - - `"move"` + The type of the shell tool. Always `shell`. - - `x: number` + - `"shell"` - 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. + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - `Screenshot object { type }` + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - A screenshot action. + - `BetaLocalEnvironment object { type, skills }` - - `type: "screenshot"` + - `BetaContainerReference object { container_id, type }` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `Custom object { name, type, allowed_callers, 3 more }` - - `"screenshot"` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `name: string` - A scroll action. + The name of the custom tool, used to identify it in tool calls. - - `scroll_x: number` + - `type: "custom"` - The horizontal scroll distance. + The type of the custom tool. Always `custom`. - - `scroll_y: number` + - `"custom"` - The vertical scroll distance. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `type: "scroll"` + The tool invocation context(s). - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `"direct"` - - `"scroll"` + - `"programmatic"` - - `x: number` + - `defer_loading: optional boolean` - The x-coordinate where the scroll occurred. + Whether this tool should be deferred and discovered via tool search. - - `y: number` + - `description: optional string` - The y-coordinate where the scroll occurred. + Optional description of the custom tool, used to provide more context. - - `keys: optional array of string` + - `format: optional object { type } or object { definition, syntax, type }` - The keys being held while scrolling. + The input format for the custom tool. Default is unconstrained text. - - `Type object { text, type }` + - `Text object { type }` - An action to type in text. + Unconstrained free-form text. - - `text: string` + - `type: "text"` - The text to type. + Unconstrained text format. Always `text`. - - `type: "type"` + - `"text"` - Specifies the event type. For a type action, this property is always set to `type`. + - `Grammar object { definition, syntax, type }` - - `"type"` + A grammar defined by the user. - - `Wait object { type }` + - `definition: string` - A wait action. + The grammar definition. - - `type: "wait"` + - `syntax: "lark" or "regex"` - Specifies the event type. For a wait action, this property is always set to `wait`. + The syntax of the grammar definition. One of `lark` or `regex`. - - `"wait"` + - `"lark"` -### Beta Computer Action List + - `"regex"` -- `BetaComputerActionList = array of BetaComputerAction` + - `type: "grammar"` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + Grammar format. Always `grammar`. - - `Click object { button, type, x, 2 more }` + - `"grammar"` - A click action. + - `Namespace object { description, name, tools, type }` - - `button: "left" or "right" or "wheel" or 2 more` + Groups function/custom tools under a shared namespace. - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `description: string` - - `"left"` + A description of the namespace shown to the model. - - `"right"` + - `name: string` - - `"wheel"` + The namespace name used in tool calls (for example, `crm`). - - `"back"` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - - `"forward"` + The function/custom tools available inside this namespace. - - `type: "click"` + - `Function object { name, type, allowed_callers, 5 more }` - Specifies the event type. For a click action, this property is always `click`. + - `name: string` - - `"click"` + - `type: "function"` - - `x: number` + - `"function"` - The x-coordinate where the click occurred. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `y: number` + The tool invocation context(s). - The y-coordinate where the click occurred. + - `"direct"` - - `keys: optional array of string` + - `"programmatic"` - The keys being held while clicking. + - `defer_loading: optional boolean` - - `DoubleClick object { keys, type, x, y }` + Whether this function should be deferred and discovered via tool search. - A double click action. + - `description: optional string` - - `keys: array of string` + - `output_schema: optional map[unknown]` - The keys being held while double-clicking. + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `type: "double_click"` + - `parameters: optional unknown` - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `strict: optional boolean` - - `"double_click"` + 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. - - `x: number` + - `Custom object { name, type, allowed_callers, 3 more }` - The x-coordinate where the double click occurred. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `y: number` + - `name: string` - The y-coordinate where the double click occurred. + The name of the custom tool, used to identify it in tool calls. - - `Drag object { path, type, keys }` + - `type: "custom"` - A drag action. + The type of the custom tool. Always `custom`. - - `path: array of object { x, y }` + - `"custom"` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `allowed_callers: optional array of "direct" or "programmatic"` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + The tool invocation context(s). - - `x: number` + - `"direct"` - The x-coordinate. + - `"programmatic"` - - `y: number` + - `defer_loading: optional boolean` - The y-coordinate. + Whether this tool should be deferred and discovered via tool search. - - `type: "drag"` + - `description: optional string` - Specifies the event type. For a drag action, this property is always set to `drag`. + Optional description of the custom tool, used to provide more context. - - `"drag"` + - `format: optional object { type } or object { definition, syntax, type }` - - `keys: optional array of string` + The input format for the custom tool. Default is unconstrained text. - The keys being held while dragging the mouse. + - `Text object { type }` - - `Keypress object { keys, type }` + Unconstrained free-form text. - A collection of keypresses the model would like to perform. + - `type: "text"` - - `keys: array of string` + Unconstrained text format. Always `text`. - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `"text"` - - `type: "keypress"` + - `Grammar object { definition, syntax, type }` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + A grammar defined by the user. - - `"keypress"` + - `definition: string` - - `Move object { type, x, y, keys }` + The grammar definition. - A mouse move action. + - `syntax: "lark" or "regex"` - - `type: "move"` + The syntax of the grammar definition. One of `lark` or `regex`. - Specifies the event type. For a move action, this property is always set to `move`. + - `"lark"` - - `"move"` + - `"regex"` - - `x: number` + - `type: "grammar"` - The x-coordinate to move to. + Grammar format. Always `grammar`. - - `y: number` + - `"grammar"` - The y-coordinate to move to. + - `type: "namespace"` - - `keys: optional array of string` + The type of the tool. Always `namespace`. - The keys being held while moving the mouse. + - `"namespace"` - - `Screenshot object { type }` + - `ToolSearch object { type, description, execution, parameters }` - A screenshot action. + Hosted or BYOT tool search configuration for deferred tools. - - `type: "screenshot"` + - `type: "tool_search"` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + The type of the tool. Always `tool_search`. - - `"screenshot"` + - `"tool_search"` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `description: optional string` - A scroll action. + Description shown to the model for a client-executed tool search tool. - - `scroll_x: number` + - `execution: optional "server" or "client"` - The horizontal scroll distance. + Whether tool search is executed by the server or by the client. - - `scroll_y: number` + - `"server"` - The vertical scroll distance. + - `"client"` - - `type: "scroll"` + - `parameters: optional unknown` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + Parameter schema for a client-executed tool search tool. - - `"scroll"` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - - `x: number` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - The x-coordinate where the scroll occurred. + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `y: number` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - The y-coordinate where the scroll occurred. + - `"web_search_preview"` - - `keys: optional array of string` + - `"web_search_preview_2025_03_11"` - The keys being held while scrolling. + - `search_content_types: optional array of "text" or "image"` - - `Type object { text, type }` + - `"text"` - An action to type in text. + - `"image"` - - `text: string` + - `search_context_size: optional "low" or "medium" or "high"` - The text to type. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `type: "type"` + - `"low"` - Specifies the event type. For a type action, this property is always set to `type`. + - `"medium"` - - `"type"` + - `"high"` - - `Wait object { type }` + - `user_location: optional object { type, city, country, 2 more }` - A wait action. + The user's location. - - `type: "wait"` + - `type: "approximate"` - Specifies the event type. For a wait action, this property is always set to `wait`. + The type of location approximation. Always `approximate`. - - `"wait"` + - `"approximate"` -### Beta Container Auto + - `city: optional string` -- `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + Free text input for the city of the user, e.g. `San Francisco`. - - `type: "container_auto"` + - `country: optional string` - Automatically creates a container for this request + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `"container_auto"` + - `region: optional string` - - `file_ids: optional array of string` + Free text input for the region of the user, e.g. `California`. - An optional list of uploaded files to make available to your code. + - `timezone: optional string` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The memory limit for the container. + - `ApplyPatch object { type, allowed_callers }` - - `"1g"` + Allows the assistant to create, delete, or update files using unified diffs. - - `"4g"` + - `type: "apply_patch"` - - `"16g"` + The type of the tool. Always `apply_patch`. - - `"64g"` + - `"apply_patch"` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `allowed_callers: optional array of "direct" or "programmatic"` - Network access policy for the container. + The tool invocation context(s). - - `BetaContainerNetworkPolicyDisabled object { type }` + - `"direct"` - - `type: "disabled"` + - `"programmatic"` - Disable outbound network access. Always `disabled`. + - `top_p: number` - - `"disabled"` + 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. - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + We generally recommend altering this or `temperature` but not both. - - `allowed_domains: array of string` + - `background: optional boolean` - A list of allowed domains when type is `allowlist`. + Whether to run the model response in the background. + [Learn more](/docs/guides/background). - - `type: "allowlist"` + - `completed_at: optional number` - Allow outbound network access only to specified domains. Always `allowlist`. + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - - `"allowlist"` + - `conversation: optional object { id }` - - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - Optional domain-scoped secrets for allowlisted domains. + - `id: string` - - `domain: string` + The unique ID of the conversation that this response was associated with. - The domain associated with the secret. + - `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 secret to inject for the domain. + - `max_tool_calls: optional number` - - `value: 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 secret value to inject for the domain. + - `moderation: optional object { input, output }` - - `skills: optional array of BetaSkillReference or BetaInlineSkill` + Moderation results for the response input and output, if moderated completions were requested. - An optional list of skills referenced by id or inline data. + - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` - - `BetaSkillReference object { skill_id, type, version }` + Moderation for the response input. - - `skill_id: string` + - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` - The ID of the referenced skill. + A moderation result produced for the response input or output. - - `type: "skill_reference"` + - `categories: map[boolean]` - References a skill created with the /v1/skills endpoint. + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `"skill_reference"` + - `category_applied_input_types: map[array of "text" or "image"]` - - `version: optional string` + Which modalities of input are reflected by the score for each category. - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `"text"` - - `BetaInlineSkill object { description, name, source, type }` + - `"image"` - - `description: string` + - `category_scores: map[number]` - The description of the skill. + A dictionary of moderation categories to scores. - - `name: string` + - `flagged: boolean` - The name of the skill. + A boolean indicating whether the content was flagged by any category. - - `source: BetaInlineSkillSource` + - `model: string` - Inline skill payload + The moderation model that produced this result. - - `data: string` + - `type: "moderation_result"` - Base64-encoded skill zip bundle. + The object type, which was always `moderation_result` for successful moderation results. - - `media_type: "application/zip"` + - `"moderation_result"` - The media type of the inline skill payload. Must be `application/zip`. + - `Error object { code, message, type }` - - `"application/zip"` + An error produced while attempting moderation for the response input or output. - - `type: "base64"` + - `code: string` - The type of the inline skill source. Must be `base64`. + The error code. - - `"base64"` + - `message: string` - - `type: "inline"` + The error message. - Defines an inline skill for this request. + - `type: "error"` - - `"inline"` + The object type, which was always `error` for moderation failures. -### Beta Container Network Policy Allowlist + - `"error"` -- `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` - - `allowed_domains: array of string` + Moderation for the response output. - A list of allowed domains when type is `allowlist`. + - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` - - `type: "allowlist"` + A moderation result produced for the response input or output. - Allow outbound network access only to specified domains. Always `allowlist`. + - `categories: map[boolean]` - - `"allowlist"` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` + - `category_applied_input_types: map[array of "text" or "image"]` - Optional domain-scoped secrets for allowlisted domains. + Which modalities of input are reflected by the score for each category. - - `domain: string` + - `"text"` - The domain associated with the secret. + - `"image"` - - `name: string` + - `category_scores: map[number]` - The name of the secret to inject for the domain. + A dictionary of moderation categories to scores. - - `value: string` + - `flagged: boolean` - The secret value to inject for the domain. + A boolean indicating whether the content was flagged by any category. -### Beta Container Network Policy Disabled + - `model: string` -- `BetaContainerNetworkPolicyDisabled object { type }` + The moderation model that produced this result. - - `type: "disabled"` + - `type: "moderation_result"` - Disable outbound network access. Always `disabled`. + The object type, which was always `moderation_result` for successful moderation results. - - `"disabled"` + - `"moderation_result"` -### Beta Container Network Policy Domain Secret + - `Error object { code, message, type }` -- `BetaContainerNetworkPolicyDomainSecret object { domain, name, value }` + An error produced while attempting moderation for the response input or output. - - `domain: string` + - `code: string` - The domain associated with the secret. + The error code. - - `name: string` + - `message: string` - The name of the secret to inject for the domain. + The error message. - - `value: string` + - `type: "error"` - The secret value to inject for the domain. + The object type, which was always `error` for moderation failures. -### Beta Container Reference + - `"error"` -- `BetaContainerReference object { container_id, type }` + - `output_text: optional string` - - `container_id: 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 ID of the referenced container. + - `previous_response_id: optional string` - - `type: "container_reference"` + 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`. - References a container created with the /v1/containers endpoint + - `prompt: optional BetaResponsePrompt` - - `"container_reference"` + Reference to a prompt template and its variables. + [Learn more](/docs/guides/text?api-mode=responses#reusable-prompts). -### Beta Easy Input Message + - `id: string` -- `BetaEasyInputMessage object { content, role, phase, type }` + The unique identifier of the prompt template to use. - 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. + - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` - - `content: string or BetaResponseInputMessageContentList` + 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. - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + - `string` - - `TextInput = string` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` A text input to the model. - - `BetaResponseInputMessageContentList = array of BetaResponseInputContent` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - A list of one or many input items to the model, containing different content - types. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - A text input to the model. + A file input to the model. - - `text: string` + - `version: optional string` - The text input to the model. + Optional version of the prompt template. - - `type: "input_text"` + - `prompt_cache_key: optional string` - The type of the input item. Always `input_text`. + 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). - - `"input_text"` + - `prompt_cache_options: optional object { mode, ttl }` - - `prompt_cache_breakpoint: optional object { mode }` + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later 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. + - `mode: "implicit" or "explicit"` - - `mode: "explicit"` + Whether implicit prompt-cache breakpoints were enabled. - The breakpoint mode. Always `explicit`. + - `"implicit"` - `"explicit"` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `ttl: "30m"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The minimum lifetime applied to each cache breakpoint. - - `detail: "low" or "high" or "auto" or "original"` + - `"30m"` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `prompt_cache_retention: optional "in_memory" or "24h"` - - `"low"` + Deprecated. Use `prompt_cache_options.ttl` instead. - - `"high"` + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. - - `"auto"` + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - - `"original"` + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - - `type: "input_image"` + - `"in_memory"` - The type of the input item. Always `input_image`. + - `"24h"` - - `"input_image"` + - `reasoning: optional object { context, effort, generate_summary, 2 more }` - - `file_id: optional string` + **gpt-5 and o-series models only** - The ID of the file to be sent to the model. + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - `image_url: optional string` + - `context: optional "auto" or "current_turn" or "all_turns"` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + Controls which reasoning items are rendered back to the model on later turns. + When returned on a response, this is the effective reasoning context mode + used for the response. - - `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. + - `"current_turn"` - - `mode: "explicit"` + - `"all_turns"` - The breakpoint mode. Always `explicit`. + - `effort: optional "none" or "minimal" or "low" or 4 more` - - `"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. - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `"none"` - A file input to the model. + - `"minimal"` - - `type: "input_file"` + - `"low"` - The type of the input item. Always `input_file`. + - `"medium"` - - `"input_file"` + - `"high"` - - `detail: optional "auto" or "low" or "high"` + - `"xhigh"` - 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`. + - `"max"` - - `"auto"` + - `generate_summary: optional "auto" or "concise" or "detailed"` - - `"low"` + **Deprecated:** use `summary` instead. - - `"high"` + 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`. - - `file_data: optional string` + - `"auto"` - The content of the file to be sent to the model. + - `"concise"` - - `file_id: optional string` + - `"detailed"` - The ID of the file to be sent to the model. + - `mode: optional string or "standard" or "pro"` - - `file_url: optional string` + Controls the reasoning execution mode for the request. - The URL of the file to be sent to the model. + When returned on a response, this is the effective execution mode. - - `filename: optional string` + - `string` - The name of the file to be sent to the model. + - `"standard" or "pro"` - - `prompt_cache_breakpoint: optional object { mode }` + Controls the reasoning execution mode for the request. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + When returned on a response, this is the effective execution mode. - - `mode: "explicit"` + - `"standard"` - The breakpoint mode. Always `explicit`. + - `"pro"` - - `"explicit"` + - `summary: optional "auto" or "concise" or "detailed"` - - `role: "user" or "assistant" or "system" or "developer"` + 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 role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - - `"user"` + - `"auto"` - - `"assistant"` + - `"concise"` - - `"system"` + - `"detailed"` - - `"developer"` + - `safety_identifier: optional string` - - `phase: optional "commentary" or "final_answer"` + 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). - 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. + - `service_tier: optional "auto" or "default" or "flex" or 2 more` - - `"commentary"` + Specifies the processing type used for serving the request. - - `"final_answer"` + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. - - `type: optional "message"` + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. - The type of the message input. Always `message`. + - `"auto"` - - `"message"` + - `"default"` -### Beta Inline Skill + - `"flex"` -- `BetaInlineSkill object { description, name, source, type }` + - `"scale"` - - `description: string` + - `"priority"` - The description of the skill. + - `status: optional BetaResponseStatus` - - `name: string` + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - The name of the skill. + - `"completed"` - - `source: BetaInlineSkillSource` + - `"failed"` - Inline skill payload + - `"in_progress"` - - `data: string` + - `"cancelled"` - Base64-encoded skill zip bundle. + - `"queued"` - - `media_type: "application/zip"` + - `"incomplete"` - The media type of the inline skill payload. Must be `application/zip`. + - `text: optional BetaResponseTextConfig` - - `"application/zip"` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - - `type: "base64"` + - [Text inputs and outputs](/docs/guides/text) + - [Structured Outputs](/docs/guides/structured-outputs) - The type of the inline skill source. Must be `base64`. + - `format: optional BetaResponseFormatTextConfig` - - `"base64"` + An object specifying the format that the model must output. - - `type: "inline"` + 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). - Defines an inline skill for this request. + The default format is `{ "type": "text" }` with no additional options. - - `"inline"` + **Not recommended for gpt-4o and newer models:** -### Beta Inline Skill Source + 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. -- `BetaInlineSkillSource object { data, media_type, type }` + - `Text object { type }` - Inline skill payload + Default response format. Used to generate text responses. - - `data: string` + - `type: "text"` - Base64-encoded skill zip bundle. + The type of response format being defined. Always `text`. - - `media_type: "application/zip"` + - `"text"` - The media type of the inline skill payload. Must be `application/zip`. + - `BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` - - `"application/zip"` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - - `type: "base64"` + - `name: string` - The type of the inline skill source. Must be `base64`. + 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. - - `"base64"` + - `schema: map[unknown]` -### Beta Local Environment + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). -- `BetaLocalEnvironment object { type, skills }` + - `type: "json_schema"` - - `type: "local"` + The type of response format being defined. Always `json_schema`. - Use a local computer environment. + - `"json_schema"` - - `"local"` + - `description: optional string` - - `skills: optional array of BetaLocalSkill` + A description of what the response format is for, used by the model to + determine how to respond in the format. - An optional list of skills. + - `strict: optional boolean` - - `description: 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 description of the skill. + - `JSONObject object { type }` - - `name: 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. - The name of the skill. + - `type: "json_object"` - - `path: string` + The type of response format being defined. Always `json_object`. - The path to the directory containing the skill. + - `"json_object"` -### Beta Local Skill + - `verbosity: optional "low" or "medium" or "high"` -- `BetaLocalSkill object { description, name, path }` + 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`. - - `description: string` + - `"low"` - The description of the skill. + - `"medium"` - - `name: string` + - `"high"` - The name of the skill. + - `top_logprobs: optional number` - - `path: 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 path to the directory containing the skill. + - `truncation: optional "auto" or "disabled"` -### Beta Response + The truncation strategy to use for the model response. -- `BetaResponse object { id, created_at, error, 31 more }` + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. - - `id: string` + - `"auto"` - Unique identifier for this Response. + - `"disabled"` - - `created_at: number` + - `usage: optional BetaResponseUsage` - Unix timestamp (in seconds) of when this Response was created. + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - - `error: BetaResponseError` + - `input_tokens: number` - An error object returned when the model fails to generate a Response. + The number of input tokens. - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 16 more` + - `input_tokens_details: object { cache_write_tokens, cached_tokens }` - The error code for the response. + A detailed breakdown of the input tokens. - - `"server_error"` + - `cache_write_tokens: number` - - `"rate_limit_exceeded"` + The number of input tokens that were written to the cache. - - `"invalid_prompt"` + - `cached_tokens: number` - - `"bio_policy"` + The number of tokens that were retrieved from the cache. + [More on prompt caching](/docs/guides/prompt-caching). - - `"vector_store_timeout"` + - `output_tokens: number` - - `"invalid_image"` + The number of output tokens. - - `"invalid_image_format"` + - `output_tokens_details: object { reasoning_tokens }` - - `"invalid_base64_image"` + A detailed breakdown of the output tokens. - - `"invalid_image_url"` + - `reasoning_tokens: number` - - `"image_too_large"` + The number of reasoning tokens. - - `"image_too_small"` + - `total_tokens: number` - - `"image_parse_error"` + The total number of tokens used. - - `"image_content_policy_violation"` + - `user: optional string` - - `"invalid_image_mode"` + 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). - - `"image_file_too_large"` + - `sequence_number: number` - - `"unsupported_image_media_type"` + The sequence number for this event. - - `"empty_image_file"` + - `type: "response.completed"` - - `"failed_to_download_image"` + The type of the event. Always `response.completed`. - - `"image_file_not_found"` + - `"response.completed"` - - `message: string` + - `agent: optional object { agent_name }` - A human-readable description of the error. + The agent that owns this multi-agent streaming event. - - `incomplete_details: object { reason }` + - `agent_name: string` - Details about why the response is incomplete. + The canonical name of the agent that produced this item. - - `reason: optional "max_output_tokens" or "content_filter"` +### Beta Response Computer Tool Call Output Screenshot - The reason why the response is incomplete. +- `BetaResponseComputerToolCallOutputScreenshot object { type, file_id, image_url }` - - `"max_output_tokens"` + A computer screenshot image used with the computer use tool. - - `"content_filter"` + - `type: "computer_screenshot"` - - `instructions: string or array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - A system (or developer) message inserted into the model's context. + - `"computer_screenshot"` - 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. + - `file_id: optional string` - - `string` + The identifier of an uploaded file that contains the screenshot. - A text input to the model, equivalent to a text input with the - `developer` role. + - `image_url: optional string` - - `InputItemList = array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + The URL of the screenshot image. - A list of one or many input items to the model, containing - different content types. +### Beta Response Container Reference - - `BetaEasyInputMessage object { content, role, phase, type }` +- `BetaResponseContainerReference object { container_id, 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. + Represents a container created with /v1/containers. - - `content: string or BetaResponseInputMessageContentList` + - `container_id: string` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + - `type: "container_reference"` - - `TextInput = string` + The environment type. Always `container_reference`. - A text input to the model. + - `"container_reference"` - - `BetaResponseInputMessageContentList = array of BetaResponseInputContent` +### Beta Response Content - A list of one or many input items to the model, containing different content - types. +- `BetaResponseContent = BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile or 3 more` + + Multi-modal input and output contents. - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` @@ -77491,7 +77865,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + An image input to the model. Learn about [image inputs](/docs/guides/vision). - `detail: "low" or "high" or "auto" or "original"` @@ -77545,124 +77919,37 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"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"` - - - `"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. + - `"low"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"high"` - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `file_data: optional string` - - `"in_progress"` + The content of the file to be sent to the model. - - `"completed"` + - `file_id: optional string` - - `"incomplete"` + The ID of the file to be sent to the model. - - `type: optional "message"` + - `file_url: optional string` - The type of the message input. Always set to `message`. + The URL of the file to be sent to the model. - - `"message"` + - `filename: optional string` - - `BetaResponseOutputMessage object { id, content, role, 4 more }` + The name of the file to be sent to the model. - An output message from the model. + - `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 output message. + - `mode: "explicit"` - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + The breakpoint mode. Always `explicit`. - The content of the output message. + - `"explicit"` - - `BetaResponseOutputText object { annotations, text, type, logprobs }` + - `BetaResponseOutputText object { annotations, logprobs, text, type }` A text output from the model. @@ -77766,17 +78053,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"file_path"` - - `text: string` - - The text output from the model. - - - `type: "output_text"` - - The type of the output text. Always `output_text`. - - - `"output_text"` - - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - `token: string` @@ -77792,6 +78069,16 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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. @@ -77806,679 +78093,547 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"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"` - - - `FileSearchCall object { id, queries, status, 3 more }` - - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `ReasoningText object { text, type }` - - `id: string` + Reasoning text from the model. - The unique ID of the file search tool call. + - `text: string` - - `queries: array of string` + The reasoning text from the model. - The queries used to search for files. + - `type: "reasoning_text"` - - `status: "in_progress" or "searching" or "completed" or 2 more` + The type of the reasoning text. Always `reasoning_text`. - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `"reasoning_text"` - - `"in_progress"` +### Beta Response Content Part Added Event - - `"searching"` +- `BetaResponseContentPartAddedEvent object { content_index, item_id, output_index, 4 more }` - - `"completed"` + Emitted when a new content part is added. - - `"incomplete"` + - `content_index: number` - - `"failed"` + The index of the content part that was added. - - `type: "file_search_call"` + - `item_id: string` - The type of the file search tool call. Always `file_search_call`. + The ID of the output item that the content part was added to. - - `"file_search_call"` + - `output_index: number` - - `agent: optional object { agent_name }` + The index of the output item that the content part was added to. - The agent that produced this item. + - `part: BetaResponseOutputText or BetaResponseOutputRefusal or object { text, type }` - - `agent_name: string` + The content part that was added. - The canonical name of the agent that produced this item. + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - - `results: optional array of object { attributes, file_id, filename, 2 more }` + A text output from the model. - The results of the file search tool call. + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` - - `attributes: optional map[string or number or boolean]` + The annotations of the text output. - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. Keys are strings - with a maximum length of 64 characters. Values are strings with a maximum - length of 512 characters, booleans, or numbers. + - `FileCitation object { file_id, filename, index, type }` - - `string` + A citation to a file. - - `number` + - `file_id: string` - - `boolean` + The ID of the file. - - `file_id: optional string` + - `filename: string` - The unique ID of the file. + The filename of the file cited. - - `filename: optional string` + - `index: number` - The name of the file. + The index of the file in the list of files. - - `score: optional number` + - `type: "file_citation"` - The relevance score of the file - a value between 0 and 1. + The type of the file citation. Always `file_citation`. - - `text: optional string` + - `"file_citation"` - The text that was retrieved from the file. + - `URLCitation object { end_index, start_index, title, 2 more }` - - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` + A citation for a web resource used to generate a model response. - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + - `end_index: number` - - `id: string` + The index of the last character of the URL citation in the message. - The unique ID of the computer call. + - `start_index: number` - - `call_id: string` + The index of the first character of the URL citation in the message. - An identifier used when responding to the tool call with output. + - `title: string` - - `pending_safety_checks: array of object { id, code, message }` + The title of the web resource. - The pending safety checks for the computer call. + - `type: "url_citation"` - - `id: string` + The type of the URL citation. Always `url_citation`. - The ID of the pending safety check. + - `"url_citation"` - - `code: optional string` + - `url: string` - The type of the pending safety check. + The URL of the web resource. - - `message: optional string` + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - Details about the pending safety check. + A citation for a container file used to generate a model response. - - `status: "in_progress" or "completed" or "incomplete"` + - `container_id: string` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The ID of the container file. - - `"in_progress"` + - `end_index: number` - - `"completed"` + The index of the last character of the container file citation in the message. - - `"incomplete"` + - `file_id: string` - - `type: "computer_call"` + The ID of the file. - The type of the computer call. Always `computer_call`. + - `filename: string` - - `"computer_call"` + The filename of the container file cited. - - `action: optional BetaComputerAction` + - `start_index: number` - A click action. + The index of the first character of the container file citation in the message. - - `Click object { button, type, x, 2 more }` + - `type: "container_file_citation"` - A click action. + The type of the container file citation. Always `container_file_citation`. - - `button: "left" or "right" or "wheel" or 2 more` + - `"container_file_citation"` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `FilePath object { file_id, index, type }` - - `"left"` + A path to a file. - - `"right"` + - `file_id: string` - - `"wheel"` + The ID of the file. - - `"back"` + - `index: number` - - `"forward"` + The index of the file in the list of files. - - `type: "click"` + - `type: "file_path"` - Specifies the event type. For a click action, this property is always `click`. + The type of the file path. Always `file_path`. - - `"click"` + - `"file_path"` - - `x: number` + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - The x-coordinate where the click occurred. + - `token: string` - - `y: number` + - `bytes: array of number` - The y-coordinate where the click occurred. + - `logprob: number` - - `keys: optional array of string` + - `top_logprobs: array of object { token, bytes, logprob }` - The keys being held while clicking. + - `token: string` - - `DoubleClick object { keys, type, x, y }` + - `bytes: array of number` - A double click action. + - `logprob: number` - - `keys: array of string` + - `text: string` - The keys being held while double-clicking. + The text output from the model. - - `type: "double_click"` + - `type: "output_text"` - Specifies the event type. For a double click action, this property is always set to `double_click`. + The type of the output text. Always `output_text`. - - `"double_click"` + - `"output_text"` - - `x: number` + - `BetaResponseOutputRefusal object { refusal, type }` - The x-coordinate where the double click occurred. + A refusal from the model. - - `y: number` + - `refusal: string` - The y-coordinate where the double click occurred. + The refusal explanation from the model. - - `Drag object { path, type, keys }` + - `type: "refusal"` - A drag action. + The type of the refusal. Always `refusal`. - - `path: array of object { x, y }` + - `"refusal"` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `ReasoningText object { text, type }` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + Reasoning text from the model. - - `x: number` + - `text: string` - The x-coordinate. + The reasoning text from the model. - - `y: number` + - `type: "reasoning_text"` - The y-coordinate. + The type of the reasoning text. Always `reasoning_text`. - - `type: "drag"` + - `"reasoning_text"` - Specifies the event type. For a drag action, this property is always set to `drag`. + - `sequence_number: number` - - `"drag"` + The sequence number of this event. - - `keys: optional array of string` + - `type: "response.content_part.added"` - The keys being held while dragging the mouse. + The type of the event. Always `response.content_part.added`. - - `Keypress object { keys, type }` + - `"response.content_part.added"` - A collection of keypresses the model would like to perform. + - `agent: optional object { agent_name }` - - `keys: array of string` + The agent that owns this multi-agent streaming event. - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `agent_name: string` - - `type: "keypress"` + The canonical name of the agent that produced this item. - Specifies the event type. For a keypress action, this property is always set to `keypress`. +### Beta Response Content Part Done Event - - `"keypress"` +- `BetaResponseContentPartDoneEvent object { content_index, item_id, output_index, 4 more }` - - `Move object { type, x, y, keys }` + Emitted when a content part is done. - A mouse move action. + - `content_index: number` - - `type: "move"` + The index of the content part that is done. - Specifies the event type. For a move action, this property is always set to `move`. + - `item_id: string` - - `"move"` + The ID of the output item that the content part was added to. - - `x: number` + - `output_index: number` - The x-coordinate to move to. + The index of the output item that the content part was added to. - - `y: number` + - `part: BetaResponseOutputText or BetaResponseOutputRefusal or object { text, type }` - The y-coordinate to move to. + The content part that is done. - - `keys: optional array of string` + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - The keys being held while moving the mouse. + A text output from the model. - - `Screenshot object { type }` + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` - A screenshot action. + The annotations of the text output. - - `type: "screenshot"` + - `FileCitation object { file_id, filename, index, type }` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + A citation to a file. - - `"screenshot"` + - `file_id: string` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + The ID of the file. - A scroll action. + - `filename: string` - - `scroll_x: number` + The filename of the file cited. - The horizontal scroll distance. + - `index: number` - - `scroll_y: number` + The index of the file in the list of files. - The vertical scroll distance. + - `type: "file_citation"` - - `type: "scroll"` + The type of the file citation. Always `file_citation`. - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `"file_citation"` - - `"scroll"` + - `URLCitation object { end_index, start_index, title, 2 more }` - - `x: number` + A citation for a web resource used to generate a model response. - The x-coordinate where the scroll occurred. + - `end_index: number` - - `y: number` + The index of the last character of the URL citation in the message. - The y-coordinate where the scroll occurred. + - `start_index: number` - - `keys: optional array of string` + The index of the first character of the URL citation in the message. - The keys being held while scrolling. + - `title: string` - - `Type object { text, type }` + The title of the web resource. - An action to type in text. + - `type: "url_citation"` - - `text: string` + The type of the URL citation. Always `url_citation`. - The text to type. + - `"url_citation"` - - `type: "type"` + - `url: string` - Specifies the event type. For a type action, this property is always set to `type`. + The URL of the web resource. - - `"type"` + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - - `Wait object { type }` + A citation for a container file used to generate a model response. - A wait action. + - `container_id: string` - - `type: "wait"` + The ID of the container file. - Specifies the event type. For a wait action, this property is always set to `wait`. + - `end_index: number` - - `"wait"` + The index of the last character of the container file citation in the message. - - `actions: optional BetaComputerActionList` + - `file_id: string` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + The ID of the file. - - `Click object { button, type, x, 2 more }` + - `filename: string` - A click action. + The filename of the container file cited. - - `DoubleClick object { keys, type, x, y }` + - `start_index: number` - A double click action. + The index of the first character of the container file citation in the message. - - `Drag object { path, type, keys }` + - `type: "container_file_citation"` - A drag action. + The type of the container file citation. Always `container_file_citation`. - - `Keypress object { keys, type }` + - `"container_file_citation"` - A collection of keypresses the model would like to perform. + - `FilePath object { file_id, index, type }` - - `Move object { type, x, y, keys }` + A path to a file. - A mouse move action. + - `file_id: string` - - `Screenshot object { type }` + The ID of the file. - A screenshot action. + - `index: number` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + The index of the file in the list of files. - A scroll action. + - `type: "file_path"` - - `Type object { text, type }` + The type of the file path. Always `file_path`. - An action to type in text. + - `"file_path"` - - `Wait object { type }` + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - A wait action. + - `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` - - `ComputerCallOutput object { call_id, output, type, 4 more }` + - `bytes: array of number` - The output of a computer tool call. + - `logprob: number` - - `call_id: string` + - `text: string` - The ID of the computer tool call that produced the output. + The text output from the model. - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `type: "output_text"` - A computer screenshot image used with the computer use tool. + The type of the output text. Always `output_text`. - - `type: "computer_screenshot"` + - `"output_text"` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `BetaResponseOutputRefusal object { refusal, type }` - - `"computer_screenshot"` + A refusal from the model. - - `file_id: optional string` + - `refusal: string` - The identifier of an uploaded file that contains the screenshot. + The refusal explanation from the model. - - `image_url: optional string` + - `type: "refusal"` - The URL of the screenshot image. + The type of the refusal. Always `refusal`. - - `type: "computer_call_output"` + - `"refusal"` - The type of the computer tool call output. Always `computer_call_output`. + - `ReasoningText object { text, type }` - - `"computer_call_output"` + Reasoning text from the model. - - `id: optional string` + - `text: string` - The ID of the computer tool call output. + The reasoning text from the model. - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `type: "reasoning_text"` - The safety checks reported by the API that have been acknowledged by the developer. + The type of the reasoning text. Always `reasoning_text`. - - `id: string` + - `"reasoning_text"` - The ID of the pending safety check. + - `sequence_number: number` - - `code: optional string` + The sequence number of this event. - The type of the pending safety check. + - `type: "response.content_part.done"` - - `message: optional string` + The type of the event. Always `response.content_part.done`. - Details about the pending safety check. + - `"response.content_part.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"` - - 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"` +### Beta Response Conversation Param - - `WebSearchCall object { id, action, status, 2 more }` +- `BetaResponseConversationParam object { id }` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + The conversation that this response belongs to. - `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. + The unique ID of the conversation. - - `"in_progress"` +### Beta Response Created Event - - `"searching"` +- `BetaResponseCreatedEvent object { response, sequence_number, type, agent }` - - `"completed"` + An event that is emitted when a response is created. - - `"failed"` + - `response: BetaResponse` - - `type: "web_search_call"` + The response that was created. - The type of the web search tool call. Always `web_search_call`. + - `id: string` - - `"web_search_call"` + Unique identifier for this Response. - - `agent: optional object { agent_name }` + - `created_at: number` - The agent that produced this item. + Unix timestamp (in seconds) of when this Response was created. - - `agent_name: string` + - `error: BetaResponseError` - The canonical name of the agent that produced this item. + An error object returned when the model fails to generate a Response. - - `FunctionCall object { arguments, call_id, name, 6 more }` + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 16 more` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + The error code for the response. - - `arguments: string` + - `"server_error"` - A JSON string of the arguments to pass to the function. + - `"rate_limit_exceeded"` - - `call_id: string` + - `"invalid_prompt"` - The unique ID of the function tool call generated by the model. + - `"bio_policy"` - - `name: string` + - `"vector_store_timeout"` - The name of the function to run. + - `"invalid_image"` - - `type: "function_call"` + - `"invalid_image_format"` - The type of the function tool call. Always `function_call`. + - `"invalid_base64_image"` - - `"function_call"` + - `"invalid_image_url"` - - `id: optional string` + - `"image_too_large"` - The unique ID of the function tool call. + - `"image_too_small"` - - `agent: optional object { agent_name }` + - `"image_parse_error"` - The agent that produced this item. + - `"image_content_policy_violation"` - - `agent_name: string` + - `"invalid_image_mode"` - The canonical name of the agent that produced this item. + - `"image_file_too_large"` - - `caller: optional object { type } or object { caller_id, type }` + - `"unsupported_image_media_type"` - The execution context that produced this tool call. + - `"empty_image_file"` - - `Direct object { type }` + - `"failed_to_download_image"` - - `type: "direct"` + - `"image_file_not_found"` - - `"direct"` + - `message: string` - - `Program object { caller_id, type }` + A human-readable description of the error. - - `caller_id: string` + - `incomplete_details: object { reason }` - The call ID of the program item that produced this tool call. + Details about why the response is incomplete. - - `type: "program"` + - `reason: optional "max_output_tokens" or "content_filter"` - - `"program"` + The reason why the response is incomplete. - - `namespace: optional string` + - `"max_output_tokens"` - The namespace of the function to run. + - `"content_filter"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `instructions: string or array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + A system (or developer) message inserted into the model's context. - - `"in_progress"` + 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. - - `"completed"` + - `string` - - `"incomplete"` + A text input to the model, equivalent to a text input with the + `developer` role. - - `FunctionCallOutput object { call_id, output, type, 4 more }` + - `InputItemList = array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` - The output of a function tool call. + A list of one or many input items to the model, containing + different content types. - - `call_id: string` + - `BetaEasyInputMessage object { content, role, phase, type }` - The unique ID of the function tool call generated by the model. + 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. - - `output: string or BetaResponseFunctionCallOutputItemList` + - `content: string or BetaResponseInputMessageContentList` - Text, image, or file output of the function tool call. + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `string` + - `TextInput = string` - A JSON string of the output of the function tool call. + A text input to the model. - - `BetaResponseFunctionCallOutputItemList = array of BetaResponseFunctionCallOutputItem` + - `BetaResponseInputMessageContentList = array of BetaResponseInputContent` - 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 }` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` A text input to the model. @@ -78502,17 +78657,11 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"explicit"` - - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - - `type: "input_image"` - - 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`. @@ -78524,6 +78673,12 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"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. @@ -78542,7 +78697,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"explicit"` - - `BetaResponseInputFileContent object { type, detail, file_data, 4 more }` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` A file input to the model. @@ -78564,7 +78719,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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` @@ -78588,149 +78743,55 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"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](https://platform.openai.com/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 }` + - `role: "user" or "assistant" or "system" or "developer"` - The agent that produced this item. + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - - `agent_name: string` + - `"user"` - The canonical name of the agent that produced this item. + - `"assistant"` - - `MultiAgentCall object { action, arguments, call_id, 3 more }` + - `"system"` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `"developer"` - The multi-agent action that was executed. + - `phase: optional "commentary" or "final_answer"` - - `"spawn_agent"` + 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. - - `"interrupt_agent"` + - `"commentary"` - - `"list_agents"` + - `"final_answer"` - - `"send_message"` + - `type: optional "message"` - - `"followup_task"` + The type of the message input. Always `message`. - - `"wait_agent"` + - `"message"` - - `arguments: string` + - `Message object { content, role, agent, 2 more }` - The action arguments as a JSON 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. - - `call_id: string` + - `content: BetaResponseInputMessageContentList` - The unique ID linking this call to its output. + A list of one or many input items to the model, containing different content + types. - - `type: "multi_agent_call"` + - `role: "user" or "system" or "developer"` - The item type. Always `multi_agent_call`. + The role of the message input. One of `user`, `system`, or `developer`. - - `"multi_agent_call"` + - `"user"` - - `id: optional string` + - `"system"` - The unique ID of this multi-agent call. + - `"developer"` - `agent: optional object { agent_name }` @@ -78740,47 +78801,46 @@ 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` + - `status: optional "in_progress" or "completed" or "incomplete"` - The multi-agent action that produced this result. + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"spawn_agent"` + - `"in_progress"` - - `"interrupt_agent"` + - `"completed"` - - `"list_agents"` + - `"incomplete"` - - `"send_message"` + - `type: optional "message"` - - `"followup_task"` + The type of the message input. Always set to `message`. - - `"wait_agent"` + - `"message"` - - `call_id: string` + - `BetaResponseOutputMessage object { id, content, role, 4 more }` - The unique ID of the multi-agent call. + An output message from the model. - - `output: array of object { text, type, annotations }` + - `id: string` - Text output returned by the multi-agent action. + The unique ID of the output message. - - `text: string` + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - The text content. + The content of the output message. - - `type: "output_text"` + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - The content type. Always `output_text`. + A text output from the model. - - `"output_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 }` - - `annotations: optional array of object { file_id, filename, index, type } or array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` + The annotations of the text output. - Citations associated with the text content. + - `FileCitation object { file_id, filename, index, type }` - - `array of object { file_id, filename, index, type }` + A citation to a file. - `file_id: string` @@ -78796,293 +78856,218 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "file_citation"` - The citation type. Always `file_citation`. + The type of the file citation. Always `file_citation`. - `"file_citation"` - - `array of object { end_index, start_index, title, 2 more }` + - `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 citation in the message. + The index of the last character of the URL citation in the message. - `start_index: number` - The index of the first character of the citation in the message. + The index of the first character of the URL citation in the message. - `title: string` - The title of the cited resource. + The title of the web resource. - `type: "url_citation"` - The citation type. Always `url_citation`. + The type of the URL citation. Always `url_citation`. - `"url_citation"` - `url: string` - The URL of the cited resource. - - - `array of object { container_id, end_index, file_id, 3 more }` - - - `container_id: string` - - The ID of the container. + The URL of the web resource. - - `end_index: number` + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - The index of the last character of the citation in the message. + A citation for a container file used to generate a model response. - - `file_id: string` + - `container_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"` + - `end_index: number` - - `status: optional "in_progress" or "completed" or "incomplete"` + The index of the last character of the container file citation in the message. - The status of the tool search call. + - `file_id: string` - - `"in_progress"` + The ID of the file. - - `"completed"` + - `filename: string` - - `"incomplete"` + The filename of the container file cited. - - `ToolSearchOutput object { tools, type, id, 4 more }` + - `start_index: 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` + The index of the first character of the container file citation in the message. - The loaded tool definitions returned by the tool search output. + - `type: "container_file_citation"` - - `Function object { name, parameters, strict, 5 more }` + The type of the container file citation. Always `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). + - `"container_file_citation"` - - `name: string` + - `FilePath object { file_id, index, type }` - The name of the function to call. + A path to a file. - - `parameters: map[unknown]` + - `file_id: string` - A JSON schema object describing the parameters of the function. + The ID of the file. - - `strict: boolean` + - `index: number` - Whether strict parameter validation is enforced for this function tool. + The index of the file in the list of files. - - `type: "function"` + - `type: "file_path"` - The type of the function tool. Always `function`. + The type of the file path. Always `file_path`. - - `"function"` + - `"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` - - `defer_loading: optional boolean` + - `top_logprobs: array of object { token, bytes, logprob }` - Whether this function is deferred and loaded via tool search. + - `token: string` - - `description: optional string` + - `bytes: array of number` - A description of the function. Used by the model to determine whether or not to call the function. + - `logprob: number` - - `output_schema: optional map[unknown]` + - `text: string` - A JSON schema object describing the JSON value encoded in string outputs for this function. + The text output from the model. - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + - `type: "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). + The type of the output text. Always `output_text`. - - `type: "file_search"` + - `"output_text"` - The type of the file search tool. Always `file_search`. + - `BetaResponseOutputRefusal object { refusal, type }` - - `"file_search"` + A refusal from the model. - - `vector_store_ids: array of string` + - `refusal: string` - The IDs of the vector stores to search. + The refusal explanation from the model. - - `filters: optional object { key, type, value } or object { filters, type }` + - `type: "refusal"` - A filter to apply. + The type of the refusal. Always `refusal`. - - `ComparisonFilter object { key, type, value }` + - `"refusal"` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `role: "assistant"` - - `key: string` + The role of the output message. Always `assistant`. - The key to compare against the value. + - `"assistant"` - - `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 message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `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: "message"` - - `"gte"` + The type of the output message. Always `message`. - - `"lt"` + - `"message"` - - `"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. + - `phase: optional "commentary" or "final_answer"` - - `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. - - `number` + - `"commentary"` - - `boolean` + - `"final_answer"` - - `array of string or number` + - `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. - - `number` + - `id: string` - - `CompoundFilter object { filters, type }` + The unique ID of the file search tool call. - Combine multiple filters using `and` or `or`. + - `queries: array of string` - - `filters: array of object { key, type, value } or unknown` + The queries used to search for files. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `status: "in_progress" or "searching" or "completed" or 2 more` - - `ComparisonFilter object { key, type, value }` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `"in_progress"` - - `key: string` + - `"searching"` - The key to compare against the value. + - `"completed"` - - `type: "eq" or "ne" or "gt" or 5 more` + - `"incomplete"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `"failed"` - - `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: "file_search_call"` - - `"eq"` + The type of the file search tool call. Always `file_search_call`. - - `"ne"` + - `"file_search_call"` - - `"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"` + - `results: optional array of object { attributes, file_id, filename, 2 more }` - - `"nin"` + The results of the file search tool call. - - `value: string or number or boolean or array of string or number` + - `attributes: optional map[string or number or boolean]` - The value to compare against the attribute key; supports string, number, or boolean types. + 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` @@ -79090,1003 +79075,984 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `boolean` - - `array of string or number` + - `file_id: optional string` - - `string` + The unique ID of the file. - - `number` + - `filename: optional string` - - `unknown` + The name of the file. - - `type: "and" or "or"` + - `score: optional number` - Type of operation: `and` or `or`. + The relevance score of the file - a value between 0 and 1. - - `"and"` + - `text: optional string` - - `"or"` + The text that was retrieved from the file. - - `max_num_results: optional number` + - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `id: string` - Ranking options for search. + The unique ID of the computer call. - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `call_id: string` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + An identifier used when responding to the tool call with output. - - `embedding_weight: number` + - `pending_safety_checks: array of object { id, code, message }` - The weight of the embedding in the reciprocal ranking fusion. + The pending safety checks for the computer call. - - `text_weight: number` + - `id: string` - The weight of the text in the reciprocal ranking fusion. + The ID of the pending safety check. - - `ranker: optional "auto" or "default-2024-11-15"` + - `code: optional string` - The ranker to use for the file search. + The type of the pending safety check. - - `"auto"` + - `message: optional string` - - `"default-2024-11-15"` + Details about the pending safety check. - - `score_threshold: optional number` + - `status: "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`. Populated when items are returned via API. - - `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`. + - `type: "computer_call"` - - `"computer"` + The type of the computer call. Always `computer_call`. - - `ComputerUsePreview object { display_height, display_width, environment, type }` + - `"computer_call"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `action: optional BetaComputerAction` - - `display_height: number` + A click action. - The height of the computer display. + - `Click object { button, type, x, 2 more }` - - `display_width: number` + A click action. - The width of the computer display. + - `button: "left" or "right" or "wheel" or 2 more` - - `environment: "windows" or "mac" or "linux" or 2 more` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - The type of computer environment to control. + - `"left"` - - `"windows"` + - `"right"` - - `"mac"` + - `"wheel"` - - `"linux"` + - `"back"` - - `"ubuntu"` + - `"forward"` - - `"browser"` + - `type: "click"` - - `type: "computer_use_preview"` + Specifies the event type. For a click action, this property is always `click`. - The type of the computer use tool. Always `computer_use_preview`. + - `"click"` - - `"computer_use_preview"` + - `x: number` - - `WebSearch object { type, filters, search_context_size, user_location }` + The x-coordinate where the click occurred. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `y: number` - - `type: "web_search" or "web_search_2025_08_26"` + The y-coordinate where the click occurred. - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `keys: optional array of string` - - `"web_search"` + The keys being held while clicking. - - `"web_search_2025_08_26"` + - `DoubleClick object { keys, type, x, y }` - - `filters: optional object { allowed_domains }` + A double click action. - Filters for the search. + - `keys: array of string` - - `allowed_domains: optional array of string` + The keys being held while double-clicking. - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `type: "double_click"` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `search_context_size: optional "low" or "medium" or "high"` + - `"double_click"` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `x: number` - - `"low"` + The x-coordinate where the double click occurred. - - `"medium"` + - `y: number` - - `"high"` + The y-coordinate where the double click occurred. - - `user_location: optional object { city, country, region, 2 more }` + - `Drag object { path, type, keys }` - The approximate location of the user. + A drag action. - - `city: optional string` + - `path: array of object { x, y }` - Free text input for the city of the user, e.g. `San Francisco`. + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `country: optional string` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `x: number` - - `region: optional string` + The x-coordinate. - Free text input for the region of the user, e.g. `California`. + - `y: number` - - `timezone: optional string` + The y-coordinate. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `type: "drag"` - - `type: optional "approximate"` + Specifies the event type. For a drag action, this property is always set to `drag`. - The type of location approximation. Always `approximate`. + - `"drag"` - - `"approximate"` + - `keys: optional array of string` - - `Mcp object { server_label, type, allowed_callers, 9 more }` + The keys being held while dragging the mouse. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `Keypress object { keys, type }` - - `server_label: string` + A collection of keypresses the model would like to perform. - A label for this MCP server, used to identify it in tool calls. + - `keys: array of string` - - `type: "mcp"` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - The type of the MCP tool. Always `mcp`. + - `type: "keypress"` - - `"mcp"` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"keypress"` - The tool invocation context(s). + - `Move object { type, x, y, keys }` - - `"direct"` + A mouse move action. - - `"programmatic"` + - `type: "move"` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + Specifies the event type. For a move action, this property is always set to `move`. - List of allowed tool names or a filter object. + - `"move"` - - `McpAllowedTools = array of string` + - `x: number` - A string array of allowed tool names + The x-coordinate to move to. - - `McpToolFilter object { read_only, tool_names }` + - `y: number` - A filter object to specify which tools are allowed. + The y-coordinate to move to. - - `read_only: optional boolean` + - `keys: 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. + The keys being held while moving the mouse. - - `tool_names: optional array of string` + - `Screenshot object { type }` - List of allowed tool names. + A screenshot action. - - `authorization: optional string` + - `type: "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. + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + - `"screenshot"` - 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - Currently supported `connector_id` values are: + A scroll action. - - 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` + - `scroll_x: number` - - `"connector_dropbox"` + The horizontal scroll distance. - - `"connector_gmail"` + - `scroll_y: number` - - `"connector_googlecalendar"` + The vertical scroll distance. - - `"connector_googledrive"` + - `type: "scroll"` - - `"connector_microsoftteams"` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `"connector_outlookcalendar"` + - `"scroll"` - - `"connector_outlookemail"` + - `x: number` - - `"connector_sharepoint"` + The x-coordinate where the scroll occurred. - - `defer_loading: optional boolean` + - `y: number` - Whether this MCP tool is deferred and discovered via tool search. + The y-coordinate where the scroll occurred. - - `headers: optional map[string]` + - `keys: optional array of string` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + The keys being held while scrolling. - - `require_approval: optional object { always, never } or "always" or "never"` + - `Type object { text, type }` - Specify which of the MCP server's tools require approval. + An action to type in text. - - `McpToolApprovalFilter object { always, never }` + - `text: string` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + The text to type. - - `always: optional object { read_only, tool_names }` + - `type: "type"` - A filter object to specify which tools are allowed. + Specifies the event type. For a type action, this property is always set to `type`. - - `read_only: optional boolean` + - `"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. + - `Wait object { type }` - - `tool_names: optional array of string` + A wait action. - List of allowed tool names. + - `type: "wait"` - - `never: optional object { read_only, tool_names }` + Specifies the event type. For a wait action, this property is always set to `wait`. - A filter object to specify which tools are allowed. + - `"wait"` - - `read_only: optional boolean` + - `actions: optional BetaComputerActionList` - 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. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `tool_names: optional array of string` + - `Click object { button, type, x, 2 more }` - List of allowed tool names. + A click action. - - `McpToolApprovalSetting = "always" or "never"` + - `DoubleClick object { keys, type, x, y }` - 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 double click action. - - `"always"` + - `Drag object { path, type, keys }` - - `"never"` + A drag action. - - `server_description: optional string` + - `Keypress object { keys, type }` - Optional description of the MCP server, used to provide more context. + A collection of keypresses the model would like to perform. - - `server_url: optional string` + - `Move object { type, x, y, keys }` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + A mouse move action. - - `tunnel_id: optional string` + - `Screenshot 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. + A screenshot action. - - `CodeInterpreter object { container, type, allowed_callers }` + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - A tool that runs Python code to help generate a response to a prompt. + A scroll action. - - `container: string or object { type, file_ids, memory_limit, network_policy }` + - `Type object { text, type }` - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + An action to type in text. - - `string` + - `Wait object { type }` - The container ID. + A wait action. - - `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"` + - `ComputerCallOutput object { call_id, output, type, 4 more }` - - `file_ids: optional array of string` + The output of a computer tool call. - 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` - - `type: "disabled"` + The URL of the screenshot image. - Disable outbound network access. Always `disabled`. + - `type: "computer_call_output"` - - `"disabled"` + The type of the computer tool call output. Always `computer_call_output`. - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `"computer_call_output"` - - `allowed_domains: array of string` + - `id: optional string` - A list of allowed domains when type is `allowlist`. + The ID of the computer tool call output. - - `type: "allowlist"` + - `acknowledged_safety_checks: optional array of object { id, code, message }` - Allow outbound network access only to specified domains. Always `allowlist`. + The safety checks reported by the API that have been acknowledged by the developer. - - `"allowlist"` + - `id: string` - - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` + The ID of the pending safety check. - Optional domain-scoped secrets for allowlisted domains. + - `code: optional string` - - `domain: string` + The type of the pending safety check. - The domain associated with the secret. + - `message: optional string` - - `name: string` + Details about the pending safety check. - The name of the secret to inject for the domain. + - `agent: optional object { agent_name }` - - `value: string` + The agent that produced this item. - The secret value to inject for the domain. + - `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`. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"code_interpreter"` + 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"` + - `WebSearchCall object { id, action, status, 2 more }` - - `ProgrammaticToolCalling object { type }` + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. - - `type: "programmatic_tool_calling"` + - `id: string` - The type of the tool. Always `programmatic_tool_calling`. + The unique ID of the web search tool call. - - `"programmatic_tool_calling"` + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - - `ImageGeneration object { type, action, background, 9 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 that generates images using the GPT image models. + - `Search object { type, queries, query, sources }` - - `type: "image_generation"` + Action type "search" - Performs a web search query. - The type of the image generation tool. Always `image_generation`. + - `type: "search"` - - `"image_generation"` + The action type. - - `action: optional "generate" or "edit" or "auto"` + - `"search"` - Whether to generate a new image or edit an existing image. Default: `auto`. + - `queries: optional array of string` - - `"generate"` + The search queries. - - `"edit"` + - `query: optional string` - - `"auto"` + The search query. - - `background: optional "transparent" or "opaque" or "auto"` + - `sources: optional array of object { type, url }` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + The sources used in the search. - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + - `type: "url"` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + The type of source. Always `url`. - - `"transparent"` + - `"url"` - - `"opaque"` + - `url: string` - - `"auto"` + The URL of the source. - - `input_fidelity: optional "high" or "low"` + - `OpenPage object { type, url }` - 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 type "open_page" - Opens a specific URL from search results. - - `"high"` + - `type: "open_page"` - - `"low"` + The action type. - - `input_image_mask: optional object { file_id, image_url }` + - `"open_page"` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `url: optional string` - - `file_id: optional string` + The URL opened by the model. - File ID for the mask image. + - `FindInPage object { pattern, type, url }` - - `image_url: optional string` + Action type "find_in_page": Searches for a pattern within a loaded page. - Base64-encoded mask image. + - `pattern: string` - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + The pattern or text to search for within the page. - The image generation model to use. Default: `gpt-image-1`. + - `type: "find_in_page"` - - `string` + The action type. - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `"find_in_page"` - The image generation model to use. Default: `gpt-image-1`. + - `url: string` - - `"gpt-image-1"` + The URL of the page searched for the pattern. - - `"gpt-image-1-mini"` + - `status: "in_progress" or "searching" or "completed" or "failed"` - - `"gpt-image-2"` + The status of the web search tool call. - - `"gpt-image-2-2026-04-21"` + - `"in_progress"` - - `"gpt-image-1.5"` + - `"searching"` - - `"chatgpt-image-latest"` + - `"completed"` - - `moderation: optional "auto" or "low"` + - `"failed"` - Moderation level for the generated image. Default: `auto`. + - `type: "web_search_call"` - - `"auto"` + The type of the web search tool call. Always `web_search_call`. - - `"low"` + - `"web_search_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"` + - `FunctionCall object { arguments, call_id, name, 6 more }` - - `"webp"` + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. - - `"jpeg"` + - `arguments: string` - - `partial_images: optional number` + A JSON string of the arguments to pass to the function. - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `call_id: string` - - `quality: optional "low" or "medium" or "high" or "auto"` + The unique ID of the function tool call generated by the model. - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `name: string` - - `"low"` + The name of the function to run. - - `"medium"` + - `type: "function_call"` - - `"high"` + The type of the function tool call. Always `function_call`. - - `"auto"` + - `"function_call"` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `id: optional string` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + The unique ID of the function tool call. - - `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"` + - `caller: optional object { type } or object { caller_id, type }` - - `"1536x1024"` + The execution context that produced this tool call. - - `"auto"` + - `Direct object { type }` - - `LocalShell object { type }` + - `type: "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. + - `"program"` - - `type: "shell"` + - `namespace: optional string` - The type of the shell tool. Always `shell`. + The namespace of the function to run. - - `"shell"` + - `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"` - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + - `FunctionCallOutput object { call_id, output, type, 4 more }` - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + The output of a function tool call. - - `type: "container_auto"` + - `call_id: string` - Automatically creates a container for this request + The unique ID of the function tool call generated by the model. - - `"container_auto"` + - `output: string or array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` - - `file_ids: optional array of string` + Text, image, or file output of the function tool call. - An optional list of uploaded files to make available to your code. + - `string` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + A JSON string of the output of the function tool call. - The memory limit for the container. + - `array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` - - `"1g"` + An array of content outputs (text, image, file) for the function tool call. - - `"4g"` + - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` - - `"16g"` + A text input to the model. - - `"64g"` + - `text: string` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + The text input to the model. - Network access policy for the container. + - `type: "input_text"` - - `BetaContainerNetworkPolicyDisabled object { type }` + The type of the input item. Always `input_text`. - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `"input_text"` - - `skills: optional array of BetaSkillReference or BetaInlineSkill` + - `prompt_cache_breakpoint: optional object { mode }` - An optional list of skills referenced by id or inline data. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `BetaSkillReference object { skill_id, type, version }` + - `mode: "explicit"` - - `skill_id: string` + The breakpoint mode. Always `explicit`. - The ID of the referenced skill. + - `"explicit"` - - `type: "skill_reference"` + - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` - References a skill created with the /v1/skills endpoint. + An image input to the model. Learn about [image inputs](/docs/guides/vision) - - `"skill_reference"` + - `type: "input_image"` - - `version: optional string` + The type of the input item. Always `input_image`. - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `"input_image"` - - `BetaInlineSkill object { description, name, source, type }` + - `detail: optional "low" or "high" or "auto" or "original"` - - `description: string` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The description of the skill. + - `"low"` - - `name: string` + - `"high"` - The name of the skill. + - `"auto"` - - `source: BetaInlineSkillSource` + - `"original"` - Inline skill payload + - `file_id: optional string` - - `data: string` + The ID of the file to be sent to the model. - Base64-encoded skill zip bundle. + - `image_url: optional string` - - `media_type: "application/zip"` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - The media type of the inline skill payload. Must be `application/zip`. + - `prompt_cache_breakpoint: optional object { mode }` - - `"application/zip"` + Marks the exact end of a reusable 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: "base64"` + - `mode: "explicit"` - The type of the inline skill source. Must be `base64`. + The breakpoint mode. Always `explicit`. - - `"base64"` + - `"explicit"` - - `type: "inline"` + - `BetaResponseInputFileContent object { type, detail, file_data, 4 more }` - Defines an inline skill for this request. + A file input to the model. - - `"inline"` + - `type: "input_file"` - - `BetaLocalEnvironment object { type, skills }` + The type of the input item. Always `input_file`. - - `type: "local"` + - `"input_file"` - Use a local computer environment. + - `detail: optional "auto" or "low" or "high"` - - `"local"` + 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`. - - `skills: optional array of BetaLocalSkill` + - `"auto"` - An optional list of skills. + - `"low"` - - `description: string` + - `"high"` - The description of the skill. + - `file_data: optional string` - - `name: string` + The base64-encoded data of the file to be sent to the model. - The name of the skill. + - `file_id: optional string` - - `path: string` + The ID of the file to be sent to the model. - The path to the directory containing the skill. + - `file_url: optional string` - - `BetaContainerReference object { container_id, type }` + The URL of the file to be sent to the model. - - `container_id: string` + - `filename: optional string` - The ID of the referenced container. + The name of the file to be sent to the model. - - `type: "container_reference"` + - `prompt_cache_breakpoint: optional object { mode }` - References a container created with the /v1/containers endpoint + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `"container_reference"` + - `mode: "explicit"` - - `Custom object { name, type, allowed_callers, 3 more }` + The breakpoint mode. Always `explicit`. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `"explicit"` - - `name: string` + - `type: "function_call_output"` - The name of the custom tool, used to identify it in tool calls. + The type of the function tool call output. Always `function_call_output`. - - `type: "custom"` + - `"function_call_output"` - The type of the custom tool. Always `custom`. + - `id: optional string` - - `"custom"` + The unique ID of the function tool call output. Populated when this item is returned via API. - - `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 }` + The caller type. Always `direct`. - The input format for the custom tool. Default is unconstrained text. + - `"direct"` - - `Text object { type }` + - `Program object { caller_id, type }` - Unconstrained free-form text. + - `caller_id: string` - - `type: "text"` + The call ID of the program item that produced this tool call. - Unconstrained text format. Always `text`. + - `type: "program"` - - `"text"` + The caller type. Always `program`. - - `Grammar object { definition, syntax, type }` + - `"program"` - A grammar defined by the user. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `definition: string` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - The grammar definition. + - `"in_progress"` - - `syntax: "lark" or "regex"` + - `"completed"` - The syntax of the grammar definition. One of `lark` or `regex`. + - `"incomplete"` - - `"lark"` + - `AgentMessage object { author, content, recipient, 3 more }` - - `"regex"` + A message routed between agents. - - `type: "grammar"` + - `author: string` - Grammar format. Always `grammar`. + The sending agent identity. - - `"grammar"` + - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` - - `Namespace object { description, name, tools, type }` + Plaintext, image, or encrypted content sent between agents. - Groups function/custom tools under a shared namespace. + - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` - - `description: string` + A text input to the model. - A description of the namespace shown to the model. + - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` - - `name: string` + An image input to the model. Learn about [image inputs](/docs/guides/vision) - The namespace name used in tool calls (for example, `crm`). + - `EncryptedContent object { encrypted_content, type }` - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - The function/custom tools available inside this namespace. + - `encrypted_content: string` - - `Function object { name, type, allowed_callers, 5 more }` + Opaque encrypted content. - - `name: string` + - `type: "encrypted_content"` - - `type: "function"` + The type of the input item. Always `encrypted_content`. - - `"function"` + - `"encrypted_content"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `recipient: string` - The tool invocation context(s). + The destination agent identity. - - `"direct"` + - `type: "agent_message"` - - `"programmatic"` + The item type. Always `agent_message`. - - `defer_loading: optional boolean` + - `"agent_message"` - Whether this function should be deferred and discovered via tool search. + - `id: optional string` - - `description: optional string` + The unique ID of this agent message item. - - `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. + - `MultiAgentCall object { action, arguments, call_id, 3 more }` - - `Custom object { name, type, allowed_callers, 3 more }` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The multi-agent action that was executed. - - `name: string` + - `"spawn_agent"` - The name of the custom tool, used to identify it in tool calls. + - `"interrupt_agent"` - - `type: "custom"` + - `"list_agents"` - The type of the custom tool. Always `custom`. + - `"send_message"` - - `"custom"` + - `"followup_task"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"wait_agent"` - The tool invocation context(s). + - `arguments: string` - - `"direct"` + The action arguments as a JSON string. - - `"programmatic"` + - `call_id: string` - - `defer_loading: optional boolean` + The unique ID linking this call to its output. - Whether this tool should be deferred and discovered via tool search. + - `type: "multi_agent_call"` - - `description: optional string` + The item type. Always `multi_agent_call`. - Optional description of the custom tool, used to provide more context. + - `"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. - - `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 }` + - `MultiAgentCallOutput object { action, call_id, output, 3 more }` - Unconstrained free-form text. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `type: "text"` + The multi-agent action that produced this result. - Unconstrained text format. Always `text`. + - `"spawn_agent"` - - `"text"` + - `"interrupt_agent"` - - `Grammar object { definition, syntax, type }` + - `"list_agents"` - A grammar defined by the user. + - `"send_message"` - - `definition: string` + - `"followup_task"` - The grammar definition. + - `"wait_agent"` - - `syntax: "lark" or "regex"` + - `call_id: string` - The syntax of the grammar definition. One of `lark` or `regex`. + The unique ID of the multi-agent call. - - `"lark"` + - `output: array of object { text, type, annotations }` - - `"regex"` + Text output returned by the multi-agent action. - - `type: "grammar"` + - `text: string` - Grammar format. Always `grammar`. + The text content. - - `"grammar"` + - `type: "output_text"` - - `type: "namespace"` + The content type. Always `output_text`. - The type of the tool. Always `namespace`. + - `"output_text"` - - `"namespace"` + - `annotations: optional array of object { file_id, filename, index, type } or array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` - - `ToolSearch object { type, description, execution, parameters }` + Citations associated with the text content. - Hosted or BYOT tool search configuration for deferred tools. + - `array of object { file_id, filename, index, type }` - - `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 file cited. - 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_citation"` - - `"server"` + The citation type. Always `file_citation`. - - `"client"` + - `"file_citation"` - - `parameters: optional unknown` + - `array of object { end_index, start_index, title, 2 more }` - Parameter schema for a client-executed tool search tool. + - `end_index: number` - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + The index of the last character of the citation in the 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). + - `start_index: number` - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + The index of the first character of the citation in the message. - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `title: string` - - `"web_search_preview"` + The title of the cited resource. - - `"web_search_preview_2025_03_11"` + - `type: "url_citation"` - - `search_content_types: optional array of "text" or "image"` + The citation type. Always `url_citation`. - - `"text"` + - `"url_citation"` - - `"image"` + - `url: string` - - `search_context_size: optional "low" or "medium" or "high"` + The URL of the cited resource. - 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. + - `array of object { container_id, end_index, file_id, 3 more }` - - `"low"` + - `container_id: string` - - `"medium"` + The ID of the container. - - `"high"` + - `end_index: number` - - `user_location: optional object { type, city, country, 2 more }` + The index of the last character of the citation in the message. - The user's location. + - `file_id: string` - - `type: "approximate"` + The ID of the container file. - The type of location approximation. Always `approximate`. + - `filename: string` - - `"approximate"` + 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 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 citation type. Always `container_file_citation`. - - `region: optional string` + - `"container_file_citation"` - Free text input for the region of the user, e.g. `California`. + - `type: "multi_agent_call_output"` - - `timezone: optional string` + The item type. Always `multi_agent_call_output`. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `"multi_agent_call_output"` - - `ApplyPatch object { type, allowed_callers }` + - `id: optional string` - Allows the assistant to create, delete, or update files using unified diffs. + The unique ID of this multi-agent call output. - - `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). + - `ToolSearchCall object { arguments, type, id, 4 more }` - - `"direct"` + - `arguments: unknown` - - `"programmatic"` + The arguments supplied to the tool search call. - - `type: "tool_search_output"` + - `type: "tool_search_call"` - The item type. Always `tool_search_output`. + The item type. Always `tool_search_call`. - - `"tool_search_output"` + - `"tool_search_call"` - `id: optional string` - The unique ID of this tool search output. + The unique ID of this tool search call. - `agent: optional object { agent_name }` @@ -80110,7 +80076,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `status: optional "in_progress" or "completed" or "incomplete"` - The status of the tool search output. + The status of the tool search call. - `"in_progress"` @@ -80118,17 +80084,11 @@ 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"` + - `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` - A list of additional tools made available at this item. + The loaded tool definitions returned by the tool search output. - `Function object { name, parameters, strict, 5 more }` @@ -80391,7 +80351,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-web-search). + [web search tool](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -80451,7 +80411,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -80503,7 +80463,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -80558,1597 +80518,726 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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"` - - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. - - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. - - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. - - - `"transparent"` - - - `"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-2" or 3 more` - - The image generation model to use. Default: `gpt-image-1`. - - - `string` - - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` - - The image generation model to use. Default: `gpt-image-1`. - - - `"gpt-image-1"` - - - `"gpt-image-1-mini"` - - - `"gpt-image-2"` - - - `"gpt-image-2-2026-04-21"` - - - `"gpt-image-1.5"` - - - `"chatgpt-image-latest"` - - - `moderation: optional "auto" or "low"` - - Moderation level for the generated image. Default: `auto`. - - - `"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](https://platform.openai.com/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](https://platform.openai.com/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 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](https://platform.openai.com/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 - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. - - - `status: optional "in_progress" or "completed" or "incomplete"` - - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `Compaction object { encrypted_content, type, id, agent }` - - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/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. + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `type: "local_shell_call_output"` + - `tool_names: optional array of string` - The type of the local shell tool call output. Always `local_shell_call_output`. + List of allowed tool names. - - `"local_shell_call_output"` + - `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` - - `status: optional "in_progress" or "completed" or "incomplete"` + List of allowed tool names. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `McpToolApprovalSetting = "always" or "never"` - - `"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. - - `"completed"` + - `"always"` - - `"incomplete"` + - `"never"` - - `ShellCall object { action, call_id, type, 5 more }` + - `server_description: optional string` - A tool representing a request to execute one or more shell commands. + Optional description of the MCP server, used to provide more context. - - `action: object { commands, max_output_length, timeout_ms }` + - `server_url: optional string` - The shell commands and limits that describe how to run the tool call. + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `commands: array of string` + - `tunnel_id: optional string` - Ordered shell commands for the execution environment to run. + 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. - - `max_output_length: optional number` + - `CodeInterpreter object { container, type, allowed_callers }` - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + A tool that runs Python code to help generate a response to a prompt. - - `timeout_ms: optional number` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - Maximum wall-clock time in milliseconds to allow the shell commands 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. - - `call_id: string` + - `string` - The unique ID of the shell tool call generated by the model. + The container ID. - - `type: "shell_call"` + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - The type of the item. Always `shell_call`. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `"shell_call"` + - `type: "auto"` - - `id: optional string` + Always `auto`. - The unique ID of the shell 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` - - `environment: optional BetaLocalEnvironment or BetaContainerReference` + A list of allowed domains when type is `allowlist`. - The environment to execute the shell commands in. + - `type: "allowlist"` - - `BetaLocalEnvironment object { type, skills }` + Allow outbound network access only to specified domains. Always `allowlist`. - - `BetaContainerReference object { container_id, type }` + - `"allowlist"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + Optional domain-scoped secrets for allowlisted domains. - - `"in_progress"` + - `domain: string` - - `"completed"` + The domain associated with the secret. - - `"incomplete"` + - `name: string` - - `ShellCallOutput object { call_id, output, type, 5 more }` + The name of the secret to inject for the domain. - The streamed output items emitted by a shell tool call. + - `value: string` - - `call_id: string` + The secret value to inject for the domain. - The unique ID of the shell tool call generated by the model. + - `type: "code_interpreter"` - - `output: array of BetaResponseFunctionShellCallOutputContent` + The type of the code interpreter tool. Always `code_interpreter`. - Captured chunks of stdout and stderr output, along with their associated outcomes. + - `"code_interpreter"` - - `outcome: object { type } or object { exit_code, type }` + - `allowed_callers: optional array of "direct" or "programmatic"` - The exit or timeout outcome associated with this shell call. + The tool invocation context(s). - - `Timeout object { type }` + - `"direct"` - Indicates that the shell call exceeded its configured time limit. + - `"programmatic"` - - `type: "timeout"` + - `ProgrammaticToolCalling object { type }` - The outcome type. Always `timeout`. + - `type: "programmatic_tool_calling"` - - `"timeout"` + The type of the tool. Always `programmatic_tool_calling`. - - `Exit object { exit_code, type }` + - `"programmatic_tool_calling"` - Indicates that the shell commands finished and returned an exit code. + - `ImageGeneration object { type, action, background, 9 more }` - - `exit_code: number` + A tool that generates images using the GPT image models. - The exit code returned by the shell process. + - `type: "image_generation"` - - `type: "exit"` + The type of the image generation tool. Always `image_generation`. - The outcome type. Always `exit`. + - `"image_generation"` - - `"exit"` + - `action: optional "generate" or "edit" or "auto"` - - `stderr: string` + Whether to generate a new image or edit an existing image. Default: `auto`. - Captured stderr output for the shell call. + - `"generate"` - - `stdout: string` + - `"edit"` - Captured stdout output for the shell call. + - `"auto"` - - `type: "shell_call_output"` + - `background: optional "transparent" or "opaque" or "auto"` - The type of the item. Always `shell_call_output`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - - `"shell_call_output"` + - `"transparent"` - - `id: optional string` + - `"opaque"` - The unique ID of the shell tool call output. Populated when this item is returned via API. + - `"auto"` - - `agent: optional object { agent_name }` + - `input_fidelity: optional "high" or "low"` - 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`. - - `agent_name: string` + - `"high"` - The canonical name of the agent that produced this item. + - `"low"` - - `caller: optional object { type } or object { caller_id, type }` + - `input_image_mask: optional object { file_id, image_url }` - The execution context that produced this tool call. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `Direct object { type }` + - `file_id: optional string` - - `type: "direct"` + File ID for the mask image. - The caller type. Always `direct`. + - `image_url: optional string` - - `"direct"` + Base64-encoded mask image. - - `Program object { caller_id, type }` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `caller_id: string` + The image generation model to use. Default: `gpt-image-1`. - The call ID of the program item that produced this tool call. + - `string` - - `type: "program"` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - The caller type. Always `program`. + The image generation model to use. Default: `gpt-image-1`. - - `"program"` + - `"gpt-image-1"` - - `max_output_length: optional number` + - `"gpt-image-1-mini"` - The maximum number of UTF-8 characters captured for this shell call's combined output. + - `"gpt-image-1.5"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `moderation: optional "auto" or "low"` - The status of the shell call output. + Moderation level for the generated image. Default: `auto`. - - `"in_progress"` + - `"auto"` - - `"completed"` + - `"low"` - - `"incomplete"` + - `output_compression: optional number` - - `ApplyPatchCall object { call_id, operation, status, 4 more }` + Compression level for the output image. Default: 100. - A tool call representing a request to create, delete, or update files using diff patches. + - `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 apply patch tool call generated by the model. + - `"png"` - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + - `"webp"` - The specific create, delete, or update instruction for the apply_patch tool call. + - `"jpeg"` - - `CreateFile object { diff, path, type }` + - `partial_images: optional number` - Instruction for creating a new file via the apply_patch tool. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `diff: string` + - `quality: optional "low" or "medium" or "high" or "auto"` - Unified diff content to apply when creating the file. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `path: string` + - `"low"` - Path of the file to create relative to the workspace root. + - `"medium"` - - `type: "create_file"` + - `"high"` - The operation type. Always `create_file`. + - `"auto"` - - `"create_file"` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `DeleteFile object { path, 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`. - Instruction for deleting an existing file via the apply_patch tool. + - `string` - - `path: string` + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - Path of the file to delete relative to the workspace root. + 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: "delete_file"` + - `"1024x1024"` - The operation type. Always `delete_file`. + - `"1024x1536"` - - `"delete_file"` + - `"1536x1024"` - - `UpdateFile object { diff, path, type }` + - `"auto"` - Instruction for updating an existing file via the apply_patch tool. + - `LocalShell object { type }` - - `diff: string` + A tool that allows the model to execute shell commands in a local environment. - Unified diff content to apply to the existing file. + - `type: "local_shell"` - - `path: string` + The type of the local shell tool. Always `local_shell`. - Path of the file to update relative to the workspace root. + - `"local_shell"` - - `type: "update_file"` + - `Shell object { type, allowed_callers, environment }` - The operation type. Always `update_file`. + A tool that allows the model to execute shell commands. - - `"update_file"` + - `type: "shell"` - - `status: "in_progress" or "completed"` + The type of the shell tool. Always `shell`. - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `"shell"` - - `"in_progress"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"completed"` + The tool invocation context(s). - - `type: "apply_patch_call"` + - `"direct"` - The type of the item. Always `apply_patch_call`. + - `"programmatic"` - - `"apply_patch_call"` + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - `id: optional string` + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `type: "container_auto"` - - `agent: optional object { agent_name }` + Automatically creates a container for this request - The agent that produced this item. + - `"container_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 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`. + - `skills: optional array of BetaSkillReference or BetaInlineSkill` - - `"program"` + An optional list of skills referenced by id or inline data. - - `ApplyPatchCallOutput object { call_id, status, type, 4 more }` + - `BetaSkillReference object { skill_id, type, version }` - The streamed output emitted by an apply patch tool call. + - `skill_id: string` - - `call_id: string` + The ID of the referenced skill. - The unique ID of the apply patch tool call generated by the model. + - `type: "skill_reference"` - - `status: "completed" or "failed"` + References a skill created with the /v1/skills endpoint. - The status of the apply patch tool call output. One of `completed` or `failed`. + - `"skill_reference"` - - `"completed"` + - `version: optional string` - - `"failed"` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `type: "apply_patch_call_output"` + - `BetaInlineSkill object { description, name, source, type }` - The type of the item. Always `apply_patch_call_output`. + - `description: string` - - `"apply_patch_call_output"` + The description of the skill. - - `id: optional string` + - `name: string` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + 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. - - `caller: optional object { type } or object { caller_id, type }` + - `media_type: "application/zip"` - The execution context that produced this tool call. + The media type of the inline skill payload. Must be `application/zip`. - - `Direct object { type }` + - `"application/zip"` - - `type: "direct"` + - `type: "base64"` - The caller type. Always `direct`. + The type of the inline skill source. Must be `base64`. - - `"direct"` + - `"base64"` - - `Program object { caller_id, type }` + - `type: "inline"` - - `caller_id: string` + Defines an inline skill for this request. - The call ID of the program item that produced this tool call. + - `"inline"` - - `type: "program"` + - `BetaLocalEnvironment object { type, skills }` - The caller type. Always `program`. + - `type: "local"` - - `"program"` + Use a local computer environment. - - `output: optional string` + - `"local"` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + - `skills: optional array of BetaLocalSkill` - - `McpListTools object { id, server_label, tools, 3 more }` + An optional list of skills. - A list of tools available on an MCP server. + - `description: string` - - `id: string` + The description of the skill. - The unique ID of the list. + - `name: string` - - `server_label: string` + The name of the skill. - The label of the MCP server. + - `path: string` - - `tools: array of object { input_schema, name, annotations, description }` + The path to the directory containing the skill. - The tools available on the server. + - `BetaContainerReference object { container_id, type }` - - `input_schema: unknown` + - `container_id: string` - The JSON schema describing the tool's input. + The ID of the referenced container. - - `name: string` + - `type: "container_reference"` - The name of the tool. + References a container created with the /v1/containers endpoint - - `annotations: optional unknown` + - `"container_reference"` - Additional annotations about the tool. + - `Custom object { name, type, allowed_callers, 3 more }` - - `description: optional string` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - The description of the tool. + - `name: string` - - `type: "mcp_list_tools"` + The name of the custom tool, used to identify it in tool calls. - The type of the item. Always `mcp_list_tools`. + - `type: "custom"` - - `"mcp_list_tools"` + 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"` - - `error: optional string` + - `"programmatic"` - Error message if the server could not list tools. + - `defer_loading: optional boolean` - - `McpApprovalRequest object { id, arguments, name, 3 more }` + Whether this tool should be deferred and discovered via tool search. - A request for human approval of a tool invocation. + - `description: optional string` - - `id: string` + Optional description of the custom tool, used to provide more context. - The unique ID of the approval request. + - `format: optional object { type } or object { definition, syntax, type }` - - `arguments: string` + The input format for the custom tool. Default is unconstrained text. - A JSON string of arguments for the tool. + - `Text object { type }` - - `name: string` + Unconstrained free-form text. - The name of the tool to run. + - `type: "text"` - - `server_label: string` + Unconstrained text format. Always `text`. - The label of the MCP server making the request. + - `"text"` - - `type: "mcp_approval_request"` + - `Grammar object { definition, syntax, type }` - The type of the item. Always `mcp_approval_request`. + A grammar defined by the user. - - `"mcp_approval_request"` + - `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"` - - `McpApprovalResponse object { approval_request_id, approve, type, 3 more }` + - `"regex"` - A response to an MCP approval request. + - `type: "grammar"` - - `approval_request_id: string` + Grammar format. Always `grammar`. - The ID of the approval request being answered. + - `"grammar"` - - `approve: boolean` + - `Namespace object { description, name, tools, type }` - Whether the request was approved. + Groups function/custom tools under a shared namespace. - - `type: "mcp_approval_response"` + - `description: string` - The type of the item. Always `mcp_approval_response`. + A description of the namespace shown to the model. - - `"mcp_approval_response"` + - `name: string` - - `id: optional string` + The namespace name used in tool calls (for example, `crm`). - The unique ID of the approval response + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - - `agent: optional object { agent_name }` + The function/custom tools available inside this namespace. - The agent that produced this item. + - `Function object { name, type, allowed_callers, 5 more }` - - `agent_name: string` + - `name: string` - The canonical name of the agent that produced this item. + - `type: "function"` - - `reason: optional string` + - `"function"` - Optional reason for the decision. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `McpCall object { id, arguments, name, 7 more }` + The tool invocation context(s). - An invocation of a tool on an MCP server. + - `"direct"` - - `id: string` + - `"programmatic"` - The unique ID of the tool call. + - `defer_loading: optional boolean` - - `arguments: string` + Whether this function should be deferred and discovered via tool search. - A JSON string of the arguments passed to the tool. + - `description: optional string` - - `name: string` + - `output_schema: optional map[unknown]` - The name of the tool that was run. + 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 running the tool. + - `strict: optional boolean` - - `type: "mcp_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. - The type of the item. Always `mcp_call`. + - `Custom object { name, type, allowed_callers, 3 more }` - - `"mcp_call"` + 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`. - - `approval_request_id: optional string` + - `"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. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `error: optional string` + The tool invocation context(s). - The error from the tool call, if any. + - `"direct"` - - `output: optional string` + - `"programmatic"` - The output from the tool call. + - `defer_loading: optional boolean` - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + Whether this tool should be deferred and discovered via tool search. - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `description: optional string` - - `"in_progress"` + Optional description of the custom tool, used to provide more context. - - `"completed"` + - `format: optional object { type } or object { definition, syntax, type }` - - `"incomplete"` + The input format for the custom tool. Default is unconstrained text. - - `"calling"` + - `Text object { type }` - - `"failed"` + Unconstrained free-form text. - - `CustomToolCallOutput object { call_id, output, type, 3 more }` + - `type: "text"` - The output of a custom tool call from your code, being sent back to the model. + Unconstrained text format. Always `text`. - - `call_id: string` + - `"text"` - The call ID, used to map this custom tool call output to a custom tool call. + - `Grammar object { definition, syntax, type }` - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + A grammar defined by the user. - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `definition: string` - - `StringOutput = string` + The grammar definition. - A string of the output of the custom tool call. + - `syntax: "lark" or "regex"` - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + The syntax of the grammar definition. One of `lark` or `regex`. - Text, image, or file output of the custom tool call. + - `"lark"` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `"regex"` - A text input to the model. + - `type: "grammar"` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + Grammar format. Always `grammar`. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `"grammar"` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `type: "namespace"` - A file input to the model. + The type of the tool. Always `namespace`. - - `type: "custom_tool_call_output"` + - `"namespace"` - The type of the custom tool call output. Always `custom_tool_call_output`. + - `ToolSearch object { type, description, execution, parameters }` - - `"custom_tool_call_output"` + Hosted or BYOT tool search configuration for deferred tools. - - `id: optional string` + - `type: "tool_search"` - The unique ID of the custom tool call output in the OpenAI platform. + 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"` - - `caller: optional object { type } or object { caller_id, type }` + Whether tool search is executed by the server or by the client. - The execution context that produced this tool call. + - `"server"` - - `Direct object { type }` + - `"client"` - - `type: "direct"` + - `parameters: optional unknown` - The caller type. Always `direct`. + Parameter schema for a client-executed tool search tool. - - `"direct"` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - - `Program object { caller_id, 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). - - `caller_id: string` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - The call ID of the program item that produced this tool call. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `type: "program"` + - `"web_search_preview"` - The caller type. Always `program`. + - `"web_search_preview_2025_03_11"` - - `"program"` + - `search_content_types: optional array of "text" or "image"` - - `CustomToolCall object { call_id, input, name, 5 more }` + - `"text"` - A call to a custom tool created by the model. + - `"image"` - - `call_id: string` + - `search_context_size: optional "low" or "medium" or "high"` - An identifier used to map this custom tool call to a 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. - - `input: string` + - `"low"` - The input for the custom tool call generated by the model. + - `"medium"` - - `name: string` + - `"high"` - The name of the custom tool being called. + - `user_location: optional object { type, city, country, 2 more }` - - `type: "custom_tool_call"` + The user's location. - The type of the custom tool call. Always `custom_tool_call`. + - `type: "approximate"` - - `"custom_tool_call"` + The type of location approximation. Always `approximate`. - - `id: optional string` + - `"approximate"` - The unique ID of the custom tool call in the OpenAI platform. + - `city: optional string` - - `agent: optional object { agent_name }` + Free text input for the city of the user, e.g. `San Francisco`. - The agent that produced this item. + - `country: optional string` - - `agent_name: string` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The canonical name of the agent that produced this item. + - `region: optional string` - - `caller: optional object { type } or object { caller_id, type }` + Free text input for the region of the user, e.g. `California`. - The execution context that produced this tool call. + - `timezone: optional string` - - `Direct object { type }` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `type: "direct"` + - `ApplyPatch object { type, allowed_callers }` - - `"direct"` + Allows the assistant to create, delete, or update files using unified diffs. - - `Program object { caller_id, type }` + - `type: "apply_patch"` - - `caller_id: string` + The type of the tool. Always `apply_patch`. - The call ID of the program item that produced this tool call. + - `"apply_patch"` - - `type: "program"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"program"` + The tool invocation context(s). - - `namespace: optional string` + - `"direct"` - The namespace of the custom tool being called. + - `"programmatic"` - - `CompactionTrigger object { type, agent }` + - `type: "tool_search_output"` - Compacts the current context. Must be the final input item. + The item type. Always `tool_search_output`. - - `type: "compaction_trigger"` + - `"tool_search_output"` - The type of the item. Always `compaction_trigger`. + - `id: optional string` - - `"compaction_trigger"` + The unique ID of this tool search output. - `agent: optional object { agent_name }` @@ -82158,1028 +81247,1038 @@ 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. + - `call_id: optional string` - - `agent: optional object { agent_name }` + The unique ID of the tool search call generated by the model. - The agent that produced this item. + - `execution: optional "server" or "client"` - - `agent_name: string` + Whether tool search was executed by the server or by the client. - The canonical name of the agent that produced this item. + - `"server"` - - `type: optional "item_reference"` + - `"client"` - The type of item to reference. Always `item_reference`. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"item_reference"` + The status of the tool search output. - - `Program object { id, call_id, code, 3 more }` + - `"in_progress"` - - `id: string` + - `"completed"` - The unique ID of this program item. + - `"incomplete"` - - `call_id: string` + - `AdditionalTools object { role, tools, type, 2 more }` - The stable call ID of the program item. + - `role: "developer"` - - `code: string` + The role that provided the additional tools. Only `developer` is supported. - The JavaScript source executed by programmatic tool calling. + - `"developer"` - - `fingerprint: 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` - Opaque program replay fingerprint that must be round-tripped. + A list of additional tools made available at this item. - - `type: "program"` + - `Function object { name, parameters, strict, 5 more }` - The item type. Always `program`. + 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). - - `"program"` + - `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` - - `ProgramOutput object { id, call_id, result, 3 more }` + Whether strict parameter validation is enforced for this function tool. - - `id: string` + - `type: "function"` - The unique ID of this program output item. + The type of the function tool. Always `function`. - - `call_id: string` + - `"function"` - 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 function is deferred and loaded via tool search. - - `"incomplete"` + - `description: optional string` - - `type: "program_output"` + A description of the function. Used by the model to determine whether or not to call the function. - The item type. Always `program_output`. + - `output_schema: optional map[unknown]` - - `"program_output"` + 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`. - - `metadata: map[string]` + - `"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. + - `vector_store_ids: array of string` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The IDs of the vector stores to search. - - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` + - `filters: optional object { key, type, value } or object { filters, 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](https://platform.openai.com/docs/models) - to browse and compare available models. + A filter to apply. - - `"gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more` + - `ComparisonFilter object { key, type, value }` - 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](https://platform.openai.com/docs/models) - to browse and compare available models. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `"gpt-5.6-sol"` + - `key: string` - - `"gpt-5.6-terra"` + The key to compare against the value. - - `"gpt-5.6-luna"` + - `type: "eq" or "ne" or "gt" or 5 more` - - `"gpt-5.4"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `"gpt-5.4-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-5.4-nano"` + - `"eq"` - - `"gpt-5.4-mini-2026-03-17"` + - `"ne"` - - `"gpt-5.4-nano-2026-03-17"` + - `"gt"` - - `"gpt-5.3-chat-latest"` + - `"gte"` - - `"gpt-5.2"` + - `"lt"` - - `"gpt-5.2-2025-12-11"` + - `"lte"` - - `"gpt-5.2-chat-latest"` + - `"in"` - - `"gpt-5.2-pro"` + - `"nin"` - - `"gpt-5.2-pro-2025-12-11"` + - `value: string or number or boolean or array of string or number` - - `"gpt-5.1"` + The value to compare against the attribute key; supports string, number, or boolean types. - - `"gpt-5.1-2025-11-13"` + - `string` - - `"gpt-5.1-codex"` + - `number` - - `"gpt-5.1-mini"` + - `boolean` - - `"gpt-5.1-chat-latest"` + - `array of string or number` - - `"gpt-5"` + - `string` - - `"gpt-5-mini"` + - `number` - - `"gpt-5-nano"` + - `CompoundFilter object { filters, type }` - - `"gpt-5-2025-08-07"` + Combine multiple filters using `and` or `or`. - - `"gpt-5-mini-2025-08-07"` + - `filters: array of object { key, type, value } or unknown` - - `"gpt-5-nano-2025-08-07"` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `"gpt-5-chat-latest"` + - `ComparisonFilter object { key, type, value }` - - `"gpt-4.1"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `"gpt-4.1-mini"` + - `key: string` - - `"gpt-4.1-nano"` + The key to compare against the value. - - `"gpt-4.1-2025-04-14"` + - `type: "eq" or "ne" or "gt" or 5 more` - - `"gpt-4.1-mini-2025-04-14"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `"gpt-4.1-nano-2025-04-14"` + - `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 - - `"o4-mini"` + - `"eq"` - - `"o4-mini-2025-04-16"` + - `"ne"` - - `"o3"` + - `"gt"` - - `"o3-2025-04-16"` + - `"gte"` - - `"o3-mini"` + - `"lt"` - - `"o3-mini-2025-01-31"` + - `"lte"` - - `"o1"` + - `"in"` - - `"o1-2024-12-17"` + - `"nin"` - - `"o1-preview"` + - `value: string or number or boolean or array of string or number` - - `"o1-preview-2024-09-12"` + The value to compare against the attribute key; supports string, number, or boolean types. - - `"o1-mini"` + - `string` - - `"o1-mini-2024-09-12"` + - `number` - - `"gpt-4o"` + - `boolean` - - `"gpt-4o-2024-11-20"` + - `array of string or number` - - `"gpt-4o-2024-08-06"` + - `string` - - `"gpt-4o-2024-05-13"` + - `number` - - `"gpt-4o-audio-preview"` + - `unknown` - - `"gpt-4o-audio-preview-2024-10-01"` + - `type: "and" or "or"` - - `"gpt-4o-audio-preview-2024-12-17"` + Type of operation: `and` or `or`. - - `"gpt-4o-audio-preview-2025-06-03"` + - `"and"` - - `"gpt-4o-mini-audio-preview"` + - `"or"` - - `"gpt-4o-mini-audio-preview-2024-12-17"` + - `max_num_results: optional number` - - `"gpt-4o-search-preview"` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `"gpt-4o-mini-search-preview"` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `"gpt-4o-search-preview-2025-03-11"` + Ranking options for search. - - `"gpt-4o-mini-search-preview-2025-03-11"` + - `hybrid_search: optional object { embedding_weight, text_weight }` - - `"chatgpt-4o-latest"` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `"codex-mini-latest"` + - `embedding_weight: number` - - `"gpt-4o-mini"` + The weight of the embedding in the reciprocal ranking fusion. - - `"gpt-4o-mini-2024-07-18"` + - `text_weight: number` - - `"gpt-4-turbo"` + The weight of the text in the reciprocal ranking fusion. - - `"gpt-4-turbo-2024-04-09"` + - `ranker: optional "auto" or "default-2024-11-15"` - - `"gpt-4-0125-preview"` + The ranker to use for the file search. - - `"gpt-4-turbo-preview"` + - `"auto"` - - `"gpt-4-1106-preview"` + - `"default-2024-11-15"` - - `"gpt-4-vision-preview"` + - `score_threshold: optional number` - - `"gpt-4"` + 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-0314"` + - `Computer object { type }` - - `"gpt-4-0613"` + 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"` + - `type: "computer"` - - `"gpt-4-32k-0314"` + The type of the computer tool. Always `computer`. - - `"gpt-4-32k-0613"` + - `"computer"` - - `"gpt-3.5-turbo"` + - `ComputerUsePreview object { display_height, display_width, environment, type }` - - `"gpt-3.5-turbo-16k"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"gpt-3.5-turbo-0301"` + - `display_height: number` - - `"gpt-3.5-turbo-0613"` + The height of the computer display. - - `"gpt-3.5-turbo-1106"` + - `display_width: number` - - `"gpt-3.5-turbo-0125"` + The width of the computer display. - - `"gpt-3.5-turbo-16k-0613"` + - `environment: "windows" or "mac" or "linux" or 2 more` - - `"o1-pro"` + The type of computer environment to control. - - `"o1-pro-2025-03-19"` + - `"windows"` - - `"o3-pro"` + - `"mac"` - - `"o3-pro-2025-06-10"` + - `"linux"` - - `"o3-deep-research"` + - `"ubuntu"` - - `"o3-deep-research-2025-06-26"` + - `"browser"` - - `"o4-mini-deep-research"` + - `type: "computer_use_preview"` - - `"o4-mini-deep-research-2025-06-26"` + The type of the computer use tool. Always `computer_use_preview`. - - `"computer-use-preview"` + - `"computer_use_preview"` - - `"computer-use-preview-2025-03-11"` + - `WebSearch object { type, filters, search_context_size, user_location }` - - `"gpt-5-codex"` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - - `"gpt-5-pro"` + - `type: "web_search" or "web_search_2025_08_26"` - - `"gpt-5-pro-2025-10-06"` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `"gpt-5.1-codex-max"` + - `"web_search"` - - `string` + - `"web_search_2025_08_26"` - - `object: "response"` + - `filters: optional object { allowed_domains }` - The object type of this resource - always set to `response`. + Filters for the search. - - `"response"` + - `allowed_domains: optional array of string` - - `output: array of BetaResponseOutputItem` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - An array of content items generated by the model. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - 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. + - `search_context_size: optional "low" or "medium" or "high"` - - `BetaResponseOutputMessage object { id, content, role, 4 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. - An output message from the model. + - `"low"` - - `FileSearchCall object { id, queries, status, 3 more }` + - `"medium"` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `"high"` - - `id: string` + - `user_location: optional object { city, country, region, 2 more }` - The unique ID of the file search tool call. + The approximate location of the user. - - `queries: array of string` + - `city: optional string` - The queries used to search for files. + Free text input for the city of the user, e.g. `San Francisco`. - - `status: "in_progress" or "searching" or "completed" or 2 more` + - `country: optional string` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + 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` - - `"searching"` + 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`. - - `"failed"` + - `type: optional "approximate"` - - `type: "file_search_call"` + The type of location approximation. Always `approximate`. - The type of the file search tool call. Always `file_search_call`. + - `"approximate"` - - `"file_search_call"` + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `agent: optional object { agent_name }` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - The agent that produced this item. + - `server_label: string` - - `agent_name: string` + A label for this MCP server, used to identify it in tool calls. - The canonical name of the agent that produced this item. + - `type: "mcp"` - - `results: optional array of object { attributes, file_id, filename, 2 more }` + The type of the MCP tool. Always `mcp`. - The results of the file search tool call. + - `"mcp"` - - `attributes: optional map[string or number or boolean]` + - `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. Keys are strings - with a maximum length of 64 characters. Values are strings with a maximum - length of 512 characters, booleans, or numbers. + The tool invocation context(s). - - `string` + - `"direct"` - - `number` + - `"programmatic"` - - `boolean` + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `file_id: optional string` + List of allowed tool names or a filter object. - The unique ID of the file. + - `McpAllowedTools = array of string` - - `filename: optional string` + A string array of allowed tool names - The name of the file. + - `McpToolFilter object { read_only, tool_names }` - - `score: optional number` + A filter object to specify which tools are allowed. - The relevance score of the file - a value between 0 and 1. + - `read_only: optional boolean` - - `text: 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 text that was retrieved from the file. + - `tool_names: optional array of string` - - `FunctionCall object { arguments, call_id, name, 6 more }` + List of allowed tool names. - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `authorization: optional string` - - `arguments: string` + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - A JSON string of the arguments to pass to the function. + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `call_id: string` + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). - The unique ID of the function tool call generated by the model. + Currently supported `connector_id` values are: - - `name: string` + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - The name of the function to run. + - `"connector_dropbox"` - - `type: "function_call"` + - `"connector_gmail"` - The type of the function tool call. Always `function_call`. + - `"connector_googlecalendar"` - - `"function_call"` + - `"connector_googledrive"` - - `id: optional string` + - `"connector_microsoftteams"` - The unique ID of the function tool call. + - `"connector_outlookcalendar"` - - `agent: optional object { agent_name }` + - `"connector_outlookemail"` - The agent that produced this item. + - `"connector_sharepoint"` - - `agent_name: string` + - `defer_loading: optional boolean` - The canonical name of the agent that produced this item. + Whether this MCP tool is deferred and discovered via tool search. - - `caller: optional object { type } or object { caller_id, type }` + - `headers: optional map[string]` - The execution context that produced this tool call. + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `Direct object { type }` + - `require_approval: optional object { always, never } or "always" or "never"` - - `type: "direct"` + Specify which of the MCP server's tools require approval. - - `"direct"` + - `McpToolApprovalFilter object { always, never }` - - `Program object { caller_id, 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. - - `caller_id: string` + - `always: optional object { read_only, tool_names }` - The call ID of the program item that produced this tool call. + A filter object to specify which tools are allowed. - - `type: "program"` + - `read_only: optional boolean` - - `"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. - - `namespace: optional string` + - `tool_names: optional array of string` - The namespace of the function to run. + List of allowed tool names. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `never: optional object { read_only, tool_names }` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when 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` - - `FunctionCallOutput object { id, call_id, output, 5 more }` + List of allowed tool names. - - `id: string` + - `McpToolApprovalSetting = "always" or "never"` - The unique ID of the function call tool 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. - - `call_id: string` + - `"always"` - The unique ID of the function tool call generated by the model. + - `"never"` - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `server_description: optional string` - The output from the function call generated by your code. - Can be a string or an list of output content. + Optional description of the MCP server, used to provide more context. - - `StringOutput = string` + - `server_url: optional string` - A string of the output of the function call. + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `tunnel_id: optional string` - Text, image, or file output of the function 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. - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `CodeInterpreter object { container, type, allowed_callers }` - A text input to the model. + A tool that runs Python code to help generate a response to a prompt. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + 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. - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `string` - A file input to the model. + The container ID. - - `status: "in_progress" or "completed" or "incomplete"` + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `"in_progress"` + - `type: "auto"` - - `"completed"` + Always `auto`. - - `"incomplete"` + - `"auto"` - - `type: "function_call_output"` + - `file_ids: optional array of string` - The type of the function tool call output. Always `function_call_output`. + An optional list of uploaded files to make available to your code. - - `"function_call_output"` + - `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"` - - `caller: optional object { type } or object { caller_id, type }` + - `"64g"` - The execution context that produced this tool call. + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `Direct object { type }` + Network access policy for the container. - - `type: "direct"` + - `BetaContainerNetworkPolicyDisabled object { type }` - The caller type. Always `direct`. + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `"direct"` + - `type: "code_interpreter"` - - `Program object { caller_id, type }` + The type of the code interpreter tool. Always `code_interpreter`. - - `caller_id: string` + - `"code_interpreter"` - 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). - The caller type. Always `program`. + - `"direct"` - - `"program"` + - `"programmatic"` - - `created_by: optional string` + - `ProgrammaticToolCalling object { type }` - The identifier of the actor that created the item. + - `type: "programmatic_tool_calling"` - - `AgentMessage object { id, author, content, 3 more }` + The type of the tool. Always `programmatic_tool_calling`. - - `id: string` + - `"programmatic_tool_calling"` - The unique ID of the agent message. + - `ImageGeneration object { type, action, background, 9 more }` - - `author: string` + A tool that generates images using the GPT image models. - The sending agent identity. + - `type: "image_generation"` - - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` + The type of the image generation tool. Always `image_generation`. - Encrypted content sent between agents. + - `"image_generation"` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `action: optional "generate" or "edit" or "auto"` - A text input to the model. + Whether to generate a new image or edit an existing image. Default: `auto`. - - `BetaResponseOutputText object { annotations, text, type, logprobs }` + - `"generate"` - A text output from the model. + - `"edit"` - - `Text object { text, type }` + - `"auto"` - A text content. + - `background: optional "transparent" or "opaque" or "auto"` - - `text: string` + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - - `type: "text"` + - `"transparent"` - - `"text"` + - `"opaque"` - - `SummaryText object { text, type }` + - `"auto"` - A summary text from the model. + - `input_fidelity: optional "high" or "low"` - - `text: 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`. - A summary of the reasoning output from the model so far. + - `"high"` - - `type: "summary_text"` + - `"low"` - The type of the object. Always `summary_text`. + - `input_image_mask: optional object { file_id, image_url }` - - `"summary_text"` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `ReasoningText object { text, type }` + - `file_id: optional string` - Reasoning text from the model. + File ID for the mask image. - - `text: string` + - `image_url: optional string` - The reasoning text from the model. + Base64-encoded mask image. - - `type: "reasoning_text"` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - The type of the reasoning text. Always `reasoning_text`. + The image generation model to use. Default: `gpt-image-1`. - - `"reasoning_text"` + - `string` - - `BetaResponseOutputRefusal object { refusal, type }` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - A refusal from the model. + The image generation model to use. Default: `gpt-image-1`. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `"gpt-image-1"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `"gpt-image-1-mini"` - - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` + - `"gpt-image-1.5"` - A screenshot of a computer. + - `moderation: optional "auto" or "low"` - - `detail: "low" or "high" or "auto" or "original"` + Moderation level for the generated image. Default: `auto`. - The detail level of the screenshot 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: string` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - The identifier of an uploaded file that contains the screenshot. + - `"png"` - - `image_url: string` + - `"webp"` - The URL of the screenshot image. + - `"jpeg"` - - `type: "computer_screenshot"` + - `partial_images: optional number` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `"computer_screenshot"` + - `quality: optional "low" or "medium" or "high" or "auto"` - - `prompt_cache_breakpoint: optional object { mode }` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `"low"` - - `mode: "explicit"` + - `"medium"` - The breakpoint mode. Always `explicit`. + - `"high"` - - `"explicit"` + - `"auto"` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - A file input to 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`. - - `EncryptedContent object { encrypted_content, type }` + - `string` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `encrypted_content: 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`. - Opaque encrypted content. + - `"1024x1024"` - - `type: "encrypted_content"` + - `"1024x1536"` - The type of the input item. Always `encrypted_content`. + - `"1536x1024"` - - `"encrypted_content"` + - `"auto"` - - `recipient: string` + - `LocalShell object { type }` - The destination agent identity. + A tool that allows the model to execute shell commands in a local environment. - - `type: "agent_message"` + - `type: "local_shell"` - The type of the item. Always `agent_message`. + The type of the local shell tool. Always `local_shell`. - - `"agent_message"` + - `"local_shell"` - - `agent: optional object { agent_name }` + - `Shell object { type, allowed_callers, environment }` - The agent that produced this item. + A tool that allows the model to execute shell commands. - - `agent_name: string` + - `type: "shell"` - The canonical name of the agent that produced this item. + The type of the shell tool. Always `shell`. - - `MultiAgentCall object { id, action, arguments, 3 more }` + - `"shell"` - - `id: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The unique ID of the multi-agent call item. + The tool invocation context(s). - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `"direct"` - The multi-agent action to execute. + - `"programmatic"` - - `"spawn_agent"` + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - `"interrupt_agent"` + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - - `"list_agents"` + - `BetaLocalEnvironment object { type, skills }` - - `"send_message"` + - `BetaContainerReference object { container_id, type }` - - `"followup_task"` + - `Custom object { name, type, allowed_callers, 3 more }` - - `"wait_agent"` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `arguments: string` + - `name: string` - The JSON string of arguments generated for the action. + The name of the custom tool, used to identify it in tool calls. - - `call_id: string` + - `type: "custom"` - The unique ID linking this call to its output. + The type of the custom tool. Always `custom`. - - `type: "multi_agent_call"` + - `"custom"` - The type of the multi-agent call. Always `multi_agent_call`. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"multi_agent_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 tool should be deferred and discovered via tool search. - - `MultiAgentCallOutput object { id, action, call_id, 3 more }` + - `description: optional string` - - `id: string` + Optional description of the custom tool, used to provide more context. - The unique ID of the multi-agent call output item. + - `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 produced this result. + - `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. - - `call_id: string` + - `definition: string` - The unique ID of the multi-agent call. + The grammar definition. - - `output: array of BetaResponseOutputText` + - `syntax: "lark" or "regex"` - Text output returned by the multi-agent action. + The syntax of the grammar definition. One of `lark` or `regex`. - - `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 }` + - `"lark"` - The annotations of the text output. + - `"regex"` - - `text: string` + - `type: "grammar"` - The text output from the model. + Grammar format. Always `grammar`. - - `type: "output_text"` + - `"grammar"` - The type of the output text. Always `output_text`. + - `Namespace object { description, name, tools, type }` - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + Groups function/custom tools under a shared namespace. - - `type: "multi_agent_call_output"` + - `description: string` - The type of the multi-agent result. Always `multi_agent_call_output`. + A description of the namespace shown to the model. - - `"multi_agent_call_output"` + - `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 }` - - `WebSearchCall object { id, action, status, 2 more }` + - `name: string` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `type: "function"` - - `id: string` + - `"function"` - 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. + - `defer_loading: optional boolean` - - `type: "search"` + Whether this function should be deferred and discovered via tool search. - The action type. + - `description: optional string` - - `"search"` + - `output_schema: optional map[unknown]` - - `queries: 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 search queries. + - `parameters: optional unknown` - - `query: optional string` + - `strict: optional boolean` - The search query. + 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. - - `sources: optional array of object { type, url }` + - `Custom object { name, type, allowed_callers, 3 more }` - The sources used in the search. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `type: "url"` + - `name: string` - The type of source. Always `url`. + The name of the custom tool, used to identify it in tool calls. - - `"url"` + - `type: "custom"` - - `url: string` + The type of the custom tool. Always `custom`. - The URL of the source. + - `"custom"` - - `OpenPage object { type, url }` + - `allowed_callers: optional array of "direct" or "programmatic"` - Action type "open_page" - Opens a specific URL from search results. + The tool invocation context(s). - - `type: "open_page"` + - `"direct"` - The action type. + - `"programmatic"` - - `"open_page"` + - `defer_loading: optional boolean` - - `url: optional string` + Whether this tool should be deferred and discovered via tool search. - The URL opened by the model. + - `description: optional string` - - `FindInPage object { pattern, type, url }` + Optional description of the custom tool, used to provide more context. - Action type "find_in_page": Searches for a pattern within a loaded page. + - `format: optional object { type } or object { definition, syntax, type }` - - `pattern: string` + The input format for the custom tool. Default is unconstrained text. - The pattern or text to search for within the page. + - `Text object { type }` - - `type: "find_in_page"` + Unconstrained free-form text. - The action type. + - `type: "text"` - - `"find_in_page"` + Unconstrained text format. Always `text`. - - `url: string` + - `"text"` - The URL of the page searched for the pattern. + - `Grammar object { definition, syntax, type }` - - `status: "in_progress" or "searching" or "completed" or "failed"` + A grammar defined by the user. - The status of the web search tool call. + - `definition: string` - - `"in_progress"` + The grammar definition. - - `"searching"` + - `syntax: "lark" or "regex"` - - `"completed"` + The syntax of the grammar definition. One of `lark` or `regex`. - - `"failed"` + - `"lark"` - - `type: "web_search_call"` + - `"regex"` - The type of the web search tool call. Always `web_search_call`. + - `type: "grammar"` - - `"web_search_call"` + 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"` - - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` + - `ToolSearch object { type, description, execution, parameters }` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + Hosted or BYOT tool search configuration for deferred tools. - - `id: string` + - `type: "tool_search"` - The unique ID of the computer call. + The type of the tool. Always `tool_search`. - - `call_id: string` + - `"tool_search"` - An identifier used when responding to the tool call with output. + - `description: optional string` - - `pending_safety_checks: array of object { id, code, message }` + Description shown to the model for a client-executed tool search tool. - The pending safety checks for the computer call. + - `execution: optional "server" or "client"` - - `id: string` + Whether tool search is executed by the server or by the client. - The ID of the pending safety check. + - `"server"` - - `code: optional string` + - `"client"` - The type of the pending safety check. + - `parameters: optional unknown` - - `message: optional string` + Parameter schema for a client-executed tool search tool. - Details about the pending safety check. + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - - `status: "in_progress" or "completed" or "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). - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `"in_progress"` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `"completed"` + - `"web_search_preview"` - - `"incomplete"` + - `"web_search_preview_2025_03_11"` - - `type: "computer_call"` + - `search_content_types: optional array of "text" or "image"` - The type of the computer call. Always `computer_call`. + - `"text"` - - `"computer_call"` + - `"image"` - - `action: optional BetaComputerAction` + - `search_context_size: optional "low" or "medium" or "high"` - A click action. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `actions: optional BetaComputerActionList` + - `"low"` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `"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 { id, call_id, output, 5 more }` + The type of location approximation. Always `approximate`. - - `id: string` + - `"approximate"` - The unique ID of the computer call tool output. + - `city: optional string` - - `call_id: string` + Free text input for the city of the user, e.g. `San Francisco`. - The ID of the computer tool call that produced the output. + - `country: optional string` - - `output: BetaResponseComputerToolCallOutputScreenshot` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - A computer screenshot image used with the computer use tool. + - `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 }` @@ -83189,16 +82288,12 @@ 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](https://platform.openai.com/docs/guides/conversation-state). + [managing context](/docs/guides/conversation-state). - `id: string` @@ -83262,29 +82357,23 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"incomplete"` - - `Program object { id, call_id, code, 3 more }` - - - `id: string` - - The unique ID of the program item. - - - `call_id: string` + - `Compaction object { encrypted_content, type, id, agent }` - The stable call ID of the program item. + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). - - `code: string` + - `encrypted_content: string` - The JavaScript source executed by programmatic tool calling. + The encrypted content of the compaction summary. - - `fingerprint: string` + - `type: "compaction"` - Opaque program replay fingerprint that must be round-tripped. + The type of the item. Always `compaction`. - - `type: "program"` + - `"compaction"` - The type of the item. Always `program`. + - `id: optional string` - - `"program"` + The ID of the compaction item. - `agent: optional object { agent_name }` @@ -83294,79 +82383,35 @@ 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` - - 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. + - `ImageGenerationCall object { id, result, status, 2 more }` - - `ToolSearchCall object { id, arguments, call_id, 5 more }` + An image generation request made by the model. - `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. + 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 }` @@ -83376,1053 +82421,958 @@ 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. - - - `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. + The unique ID of the code interpreter tool call. - - `type: "function"` + - `code: string` - The type of the function tool. Always `function`. + The code to run, or null if not available. - - `"function"` + - `container_id: string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The ID of the container used to run the code. - The tool invocation context(s). + - `outputs: array of object { logs, type } or object { type, url }` - - `"direct"` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `"programmatic"` + - `Logs object { logs, type }` - - `defer_loading: optional boolean` + The logs output from the code interpreter. - Whether this function is deferred and loaded via tool search. + - `logs: string` - - `description: optional string` + The logs output from the code interpreter. - 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]` + The type of the output. 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 }` + - `Image object { type, url }` - 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 image output from the code interpreter. - - `type: "file_search"` + - `type: "image"` - The type of the file search tool. Always `file_search`. + The type of the output. Always `image`. - - `"file_search"` + - `"image"` - - `vector_store_ids: array of string` + - `url: string` - The IDs of the vector stores to search. + The URL of the image output from the code interpreter. - - `filters: optional object { key, type, value } or object { filters, type }` + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - A filter to apply. + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `ComparisonFilter object { key, type, value }` + - `"in_progress"` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `"completed"` - - `key: string` + - `"incomplete"` - The key to compare against the value. + - `"interpreting"` - - `type: "eq" or "ne" or "gt" or 5 more` + - `"failed"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `type: "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 + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `"eq"` + - `"code_interpreter_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"` + - `LocalShellCall object { id, action, call_id, 3 more }` - - `"in"` + A tool call to run a command on the local shell. - - `"nin"` + - `id: string` - - `value: string or number or boolean or array of string or number` + The unique ID of the local shell call. - The value to compare against the attribute key; supports string, number, or boolean types. + - `action: object { command, env, type, 3 more }` - - `string` + Execute a shell command on the server. - - `number` + - `command: array of string` - - `boolean` + The command to run. - - `array of string or number` + - `env: map[string]` - - `string` + Environment variables to set for the command. - - `number` + - `type: "exec"` - - `CompoundFilter object { filters, type }` + The type of the local shell action. Always `exec`. - Combine multiple filters using `and` or `or`. + - `"exec"` - - `filters: array of object { key, type, value } or unknown` + - `timeout_ms: optional number` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + Optional timeout in milliseconds for the command. - - `ComparisonFilter object { key, type, value }` + - `user: optional string` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + Optional user to run the command as. - - `key: string` + - `working_directory: optional string` - The key to compare against the value. + Optional working directory to run the command in. - - `type: "eq" or "ne" or "gt" or 5 more` + - `call_id: string` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The unique ID of the local shell tool call generated by the model. - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `status: "in_progress" or "completed" or "incomplete"` - - `"eq"` + The status of the local shell call. - - `"ne"` + - `"in_progress"` - - `"gt"` + - `"completed"` - - `"gte"` + - `"incomplete"` - - `"lt"` + - `type: "local_shell_call"` - - `"lte"` + The type of the local shell call. Always `local_shell_call`. - - `"in"` + - `"local_shell_call"` - - `"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` + - `LocalShellCallOutput object { id, output, type, 2 more }` - - `boolean` + The output of a local shell tool call. - - `array of string or number` + - `id: string` - - `string` + The unique ID of the local shell tool call generated by the model. - - `number` + - `output: string` - - `unknown` + A JSON string of the output of the local shell tool call. - - `type: "and" or "or"` + - `type: "local_shell_call_output"` - Type of operation: `and` or `or`. + The type of the local shell tool call output. Always `local_shell_call_output`. - - `"and"` + - `"local_shell_call_output"` - - `"or"` + - `agent: optional object { agent_name }` - - `max_num_results: optional number` + The agent that produced this item. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `agent_name: string` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + The canonical name of the agent that produced this item. - Ranking options for search. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `hybrid_search: optional object { embedding_weight, text_weight }` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - 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` + - `ShellCall object { action, call_id, type, 5 more }` - The weight of the text in the reciprocal ranking fusion. + A tool representing a request to execute one or more shell commands. - - `ranker: optional "auto" or "default-2024-11-15"` + - `action: object { commands, max_output_length, timeout_ms }` - The ranker to use for the file search. + The shell commands and limits that describe how to run the tool call. - - `"auto"` + - `commands: array of string` - - `"default-2024-11-15"` + Ordered shell commands for the execution environment to run. - - `score_threshold: optional number` + - `max_output_length: 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 UTF-8 characters to capture from combined stdout and stderr output. - - `Computer object { type }` + - `timeout_ms: optional number` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + Maximum wall-clock time in milliseconds to allow the shell commands to run. - - `type: "computer"` + - `call_id: string` - The type of the computer tool. Always `computer`. + The unique ID of the shell tool call generated by the model. - - `"computer"` + - `type: "shell_call"` - - `ComputerUsePreview object { display_height, display_width, environment, type }` + The type of the item. Always `shell_call`. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `"shell_call"` - - `display_height: number` + - `id: optional string` - The height of the computer display. + The unique ID of the shell tool call. Populated when this item is returned via API. - - `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"` + - `caller: optional object { type } or object { caller_id, type }` - - `"mac"` + The execution context that produced this tool call. - - `"linux"` + - `Direct object { type }` - - `"ubuntu"` + - `type: "direct"` - - `"browser"` + The caller type. Always `direct`. - - `type: "computer_use_preview"` + - `"direct"` - The type of the computer use tool. Always `computer_use_preview`. + - `Program object { caller_id, type }` - - `"computer_use_preview"` + - `caller_id: string` - - `WebSearch object { type, filters, search_context_size, user_location }` + The call ID of the program item that produced this tool call. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `type: "program"` - - `type: "web_search" or "web_search_2025_08_26"` + The caller type. Always `program`. - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `"program"` - - `"web_search"` + - `environment: optional BetaLocalEnvironment or BetaContainerReference` - - `"web_search_2025_08_26"` + The environment to execute the shell commands in. - - `filters: optional object { allowed_domains }` + - `BetaLocalEnvironment object { type, skills }` - Filters for the search. + - `BetaContainerReference object { container_id, type }` - - `allowed_domains: optional array of string` + - `status: optional "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 shell call. One of `in_progress`, `completed`, or `incomplete`. - 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"` + - `ShellCallOutput object { call_id, output, type, 5 more }` - - `"medium"` + The streamed output items emitted by a shell tool call. - - `"high"` + - `call_id: string` - - `user_location: optional object { city, country, region, 2 more }` + The unique ID of the shell tool call generated by the model. - The approximate location of the user. + - `output: array of BetaResponseFunctionShellCallOutputContent` - - `city: optional string` + Captured chunks of stdout and stderr output, along with their associated outcomes. - Free text input for the city of the user, e.g. `San Francisco`. + - `outcome: object { type } or object { exit_code, type }` - - `country: optional string` + The exit or timeout outcome associated with this shell call. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `Timeout object { type }` - - `region: optional string` + Indicates that the shell call exceeded its configured time limit. - Free text input for the region of the user, e.g. `California`. + - `type: "timeout"` - - `timezone: optional string` + The outcome type. Always `timeout`. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `"timeout"` - - `type: optional "approximate"` + - `Exit object { exit_code, type }` - The type of location approximation. Always `approximate`. + Indicates that the shell commands finished and returned an exit code. - - `"approximate"` + - `exit_code: number` - - `Mcp object { server_label, type, allowed_callers, 9 more }` + The exit code returned by the shell process. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `type: "exit"` - - `server_label: string` + The outcome type. Always `exit`. - A label for this MCP server, used to identify it in tool calls. + - `"exit"` - - `type: "mcp"` + - `stderr: string` - The type of the MCP tool. Always `mcp`. + Captured stderr output for the shell call. - - `"mcp"` + - `stdout: string` - - `allowed_callers: optional array of "direct" or "programmatic"` + Captured stdout output for the shell call. - The tool invocation context(s). + - `type: "shell_call_output"` - - `"direct"` + The type of the item. Always `shell_call_output`. - - `"programmatic"` + - `"shell_call_output"` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + - `id: optional string` - List of allowed tool names or a filter object. + The unique ID of the shell tool call output. Populated when this item is returned via API. - - `McpAllowedTools = array of string` + - `agent: optional object { agent_name }` - A string array of allowed tool names + The agent that produced this item. - - `McpToolFilter 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` + - `caller: optional object { type } or 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. + The execution context that produced this tool call. - - `tool_names: optional array of string` + - `Direct object { type }` - List of allowed tool names. + - `type: "direct"` - - `authorization: optional string` + The caller type. Always `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. + - `"direct"` - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + - `Program object { caller_id, 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + - `caller_id: string` - Currently supported `connector_id` values are: + The call ID of the program item that produced this tool 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` + - `type: "program"` - - `"connector_dropbox"` + The caller type. Always `program`. - - `"connector_gmail"` + - `"program"` - - `"connector_googlecalendar"` + - `max_output_length: optional number` - - `"connector_googledrive"` + The maximum number of UTF-8 characters captured for this shell call's combined output. - - `"connector_microsoftteams"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"connector_outlookcalendar"` + The status of the shell call output. - - `"connector_outlookemail"` + - `"in_progress"` - - `"connector_sharepoint"` + - `"completed"` - - `defer_loading: optional boolean` + - `"incomplete"` - Whether this MCP tool is deferred and discovered via tool search. + - `ApplyPatchCall object { call_id, operation, status, 4 more }` - - `headers: optional map[string]` + A tool call representing a request to create, delete, or update files using diff patches. - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `call_id: string` - - `require_approval: optional object { always, never } or "always" or "never"` + The unique ID of the apply patch tool call generated by the model. - Specify which of the MCP server's tools require approval. + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - - `McpToolApprovalFilter object { always, never }` + The specific create, delete, or update instruction for the apply_patch 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. + - `CreateFile object { diff, path, type }` - - `always: optional object { read_only, tool_names }` + Instruction for creating a new file via the apply_patch tool. - A filter object to specify which tools are allowed. + - `diff: string` - - `read_only: optional boolean` + Unified diff content to apply when creating 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. + - `path: string` - - `tool_names: optional array of string` + Path of the file to create relative to the workspace root. - List of allowed tool names. + - `type: "create_file"` - - `never: optional object { read_only, tool_names }` + The operation type. Always `create_file`. - A filter object to specify which tools are allowed. + - `"create_file"` - - `read_only: optional boolean` + - `DeleteFile object { path, 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. + Instruction for deleting an existing file via the apply_patch tool. - - `tool_names: optional array of string` + - `path: string` - List of allowed tool names. + Path of the file to delete relative to the workspace root. - - `McpToolApprovalSetting = "always" or "never"` + - `type: "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. + The operation type. Always `delete_file`. - - `"always"` + - `"delete_file"` - - `"never"` + - `UpdateFile object { diff, path, type }` - - `server_description: optional string` + Instruction for updating an existing file via the apply_patch tool. - Optional description of the MCP server, used to provide more context. + - `diff: string` - - `server_url: optional string` + Unified diff content to apply to the existing file. - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `path: string` - - `tunnel_id: optional string` + Path of the file to update relative to the workspace root. - 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: "update_file"` - - `CodeInterpreter object { container, type, allowed_callers }` + The operation type. Always `update_file`. - A tool that runs Python code to help generate a response to a prompt. + - `"update_file"` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + - `status: "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. + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `string` + - `"in_progress"` - The container ID. + - `"completed"` - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + - `type: "apply_patch_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 `apply_patch_call`. - - `type: "auto"` + - `"apply_patch_call"` - Always `auto`. + - `id: optional string` - - `"auto"` + The unique ID of the apply patch 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 }` - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `caller_id: string` - - `type: "code_interpreter"` + The call ID of the program item that produced this tool call. - The type of the code interpreter tool. Always `code_interpreter`. + - `type: "program"` - - `"code_interpreter"` + The caller type. Always `program`. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"program"` - The tool invocation context(s). + - `ApplyPatchCallOutput object { call_id, status, type, 4 more }` - - `"direct"` + The streamed output emitted by an apply patch tool call. - - `"programmatic"` + - `call_id: string` - - `ProgrammaticToolCalling object { type }` + The unique ID of the apply patch tool call generated by the model. - - `type: "programmatic_tool_calling"` + - `status: "completed" or "failed"` - The type of the tool. Always `programmatic_tool_calling`. + The status of the apply patch tool call output. One of `completed` or `failed`. - - `"programmatic_tool_calling"` + - `"completed"` - - `ImageGeneration object { type, action, background, 9 more }` + - `"failed"` - A tool that generates images using the GPT image models. + - `type: "apply_patch_call_output"` - - `type: "image_generation"` + The type of the item. Always `apply_patch_call_output`. - The type of the image generation tool. Always `image_generation`. + - `"apply_patch_call_output"` - - `"image_generation"` + - `id: optional string` - - `action: optional "generate" or "edit" or "auto"` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - 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"` + - `caller: optional object { type } or object { caller_id, type }` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + The execution context that produced this tool call. - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + - `Direct object { type }` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `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). + - `output: optional string` - - `file_id: optional string` + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - File ID for the mask image. + - `McpListTools object { id, server_label, tools, 3 more }` - - `image_url: optional string` + A list of tools available on an MCP server. - Base64-encoded mask image. + - `id: string` - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + The unique ID of the list. - The image generation model to use. Default: `gpt-image-1`. + - `server_label: string` - - `string` + The label of the MCP server. - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `tools: array of object { input_schema, name, annotations, description }` - The image generation model to use. Default: `gpt-image-1`. + The tools available on the server. - - `"gpt-image-1"` + - `input_schema: unknown` - - `"gpt-image-1-mini"` + The JSON schema describing the tool's input. - - `"gpt-image-2"` + - `name: string` - - `"gpt-image-2-2026-04-21"` + The name of the tool. - - `"gpt-image-1.5"` + - `annotations: optional unknown` - - `"chatgpt-image-latest"` + Additional annotations about the tool. - - `moderation: optional "auto" or "low"` + - `description: optional string` - Moderation level for the generated image. Default: `auto`. + The description of the tool. - - `"auto"` + - `type: "mcp_list_tools"` - - `"low"` + The type of the item. Always `mcp_list_tools`. - - `output_compression: optional number` + - `"mcp_list_tools"` - Compression level for the output image. Default: 100. + - `agent: optional object { agent_name }` - - `output_format: optional "png" or "webp" or "jpeg"` + The agent that produced this item. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `agent_name: string` - - `"png"` + The canonical name of the agent that produced this item. - - `"webp"` + - `error: optional string` - - `"jpeg"` + Error message if the server could not list tools. - - `partial_images: optional number` + - `McpApprovalRequest object { id, arguments, name, 3 more }` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + A request for human approval of a tool invocation. - - `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`. + The unique ID of the approval request. - - `"low"` + - `arguments: string` - - `"medium"` + A JSON string of arguments for the tool. - - `"high"` + - `name: string` - - `"auto"` + The name of the tool to run. - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `server_label: 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 label of the MCP server making the request. - - `string` + - `type: "mcp_approval_request"` - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + The type of the item. Always `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`. + - `"mcp_approval_request"` - - `"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 }` + - `McpApprovalResponse object { approval_request_id, approve, type, 3 more }` - A tool that allows the model to execute shell commands in a local environment. + A response to an MCP approval request. - - `type: "local_shell"` + - `approval_request_id: string` - The type of the local shell tool. Always `local_shell`. + The ID of the approval request being answered. - - `"local_shell"` + - `approve: boolean` - - `Shell object { type, allowed_callers, environment }` + Whether the request was approved. - A tool that allows the model to execute shell commands. + - `type: "mcp_approval_response"` - - `type: "shell"` + The type of the item. Always `mcp_approval_response`. - The type of the shell tool. Always `shell`. + - `"mcp_approval_response"` - - `"shell"` + - `id: optional string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The unique ID of the approval response - 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 }` + - `reason: optional string` - - `BetaLocalEnvironment object { type, skills }` + Optional reason for the decision. - - `BetaContainerReference object { container_id, type }` + - `McpCall object { id, arguments, name, 7 more }` - - `Custom object { name, type, allowed_callers, 3 more }` + An invocation of a tool on an MCP server. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `id: string` - - `name: string` + The unique ID of the tool call. - The name of the custom tool, used to identify it in tool calls. + - `arguments: string` - - `type: "custom"` + A JSON string of the arguments passed to the tool. - The type of the custom tool. Always `custom`. + - `name: string` - - `"custom"` + 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`. - - `defer_loading: optional boolean` + - `"mcp_call"` - Whether this tool should be deferred and discovered via tool search. + - `agent: optional object { agent_name }` - - `description: optional string` + The agent that produced this item. - 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. + - `approval_request_id: optional string` - - `Text 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. - Unconstrained free-form text. + - `error: optional string` - - `type: "text"` + The error from the tool call, if any. - Unconstrained text format. Always `text`. + - `output: optional string` - - `"text"` + The output from the tool call. - - `Grammar object { definition, syntax, type }` + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - A grammar defined by the user. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `definition: string` + - `"in_progress"` - The grammar definition. + - `"completed"` - - `syntax: "lark" or "regex"` + - `"incomplete"` - The syntax of the grammar definition. One of `lark` or `regex`. + - `"calling"` - - `"lark"` + - `"failed"` - - `"regex"` + - `CustomToolCallOutput object { call_id, output, type, 3 more }` - - `type: "grammar"` + The output of a custom tool call from your code, being sent back to the model. - Grammar format. Always `grammar`. + - `call_id: string` - - `"grammar"` + The call ID, used to map this custom tool call output to a custom tool call. - - `Namespace object { description, name, tools, type }` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - Groups function/custom tools under a shared namespace. + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `description: string` + - `StringOutput = string` - A description of the namespace shown to the model. + A string of the output of the custom tool call. - - `name: string` + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - The namespace name used in tool calls (for example, `crm`). + Text, image, or file output of the custom tool call. - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - The function/custom tools available inside this namespace. + A text input to the model. - - `Function object { name, type, allowed_callers, 5 more }` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `name: string` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `type: "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: "custom_tool_call_output"` - The tool invocation context(s). + The type of the custom tool call output. Always `custom_tool_call_output`. - - `"direct"` + - `"custom_tool_call_output"` - - `"programmatic"` + - `id: optional string` - - `defer_loading: optional boolean` + The unique ID of the custom tool call output in the OpenAI platform. - Whether this function should be deferred and discovered via tool search. + - `agent: optional object { agent_name }` - - `description: optional string` + The agent that produced this item. - - `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` + - `caller: optional object { type } or object { caller_id, type }` - - `strict: optional boolean` + The execution context that produced this tool 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. + - `Direct object { type }` - - `Custom object { name, type, allowed_callers, 3 more }` + - `type: "direct"` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The caller type. Always `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"` + The caller type. Always `program`. - The tool invocation context(s). + - `"program"` - - `"direct"` + - `CustomToolCall object { call_id, input, name, 5 more }` - - `"programmatic"` + A call to a custom tool created by the model. - - `defer_loading: optional boolean` + - `call_id: string` - Whether this tool should be deferred and discovered via tool search. + An identifier used to map this custom tool call to a tool call output. - - `description: optional string` + - `input: string` - Optional description of the custom tool, used to provide more context. + The input for the custom tool call generated by the model. - - `format: optional object { type } or object { definition, syntax, type }` + - `name: string` - The input format for the custom tool. Default is unconstrained text. + The name of the custom tool being called. - - `Text object { type }` + - `type: "custom_tool_call"` - Unconstrained free-form text. + The type of the custom tool call. Always `custom_tool_call`. - - `type: "text"` + - `"custom_tool_call"` - Unconstrained text format. Always `text`. + - `id: optional string` - - `"text"` + The unique ID of the custom tool call in the OpenAI platform. - - `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"` + - `"direct"` - Grammar format. Always `grammar`. + - `Program object { caller_id, type }` - - `"grammar"` + - `caller_id: string` - - `type: "namespace"` + The call ID of the program item that produced this tool call. - The type of the tool. Always `namespace`. + - `type: "program"` - - `"namespace"` + - `"program"` - - `ToolSearch object { type, description, execution, parameters }` + - `namespace: optional string` - Hosted or BYOT tool search configuration for deferred tools. + The namespace of the custom tool being called. - - `type: "tool_search"` + - `CompactionTrigger object { type, agent }` - The type of the tool. Always `tool_search`. + Compacts the current context. Must be the final input item. - - `"tool_search"` + - `type: "compaction_trigger"` - - `description: optional string` + The type of the item. Always `compaction_trigger`. - Description shown to the model for a client-executed tool search tool. + - `"compaction_trigger"` - - `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` + - `ItemReference object { id, agent, type }` - Parameter schema for a client-executed tool search tool. + An internal identifier for an item to reference. - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + - `id: string` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The ID of the item to reference. - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `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"` + - `type: optional "item_reference"` - - `"text"` + The type of item to reference. Always `item_reference`. - - `"image"` + - `"item_reference"` - - `search_context_size: optional "low" or "medium" or "high"` + - `Program object { id, call_id, code, 3 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 this program item. - - `"medium"` + - `call_id: string` - - `"high"` + The stable call ID of the program item. - - `user_location: optional object { type, city, country, 2 more }` + - `code: string` - The user's location. + The JavaScript source executed by programmatic tool calling. - - `type: "approximate"` + - `fingerprint: string` - The type of location approximation. Always `approximate`. + Opaque program replay fingerprint that must be round-tripped. - - `"approximate"` + - `type: "program"` - - `city: optional string` + The item type. Always `program`. - Free text input for the city of the user, e.g. `San Francisco`. + - `"program"` - - `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` + - `ProgramOutput object { id, call_id, result, 3 more }` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `id: string` - - `ApplyPatch object { type, allowed_callers }` + The unique ID of this program output item. - Allows the assistant to create, delete, or update files using unified diffs. + - `call_id: string` - - `type: "apply_patch"` + The call ID of the program item. - The type of the tool. Always `apply_patch`. + - `result: string` - - `"apply_patch"` + 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. - - `"direct"` + - `"completed"` - - `"programmatic"` + - `"incomplete"` - - `type: "tool_search_output"` + - `type: "program_output"` - The type of the item. Always `tool_search_output`. + The item type. Always `program_output`. - - `"tool_search_output"` + - `"program_output"` - `agent: optional object { agent_name }` @@ -84432,1051 +83382,1043 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `created_by: optional string` + - `metadata: map[string]` - 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. - - `AdditionalTools object { id, role, tools, 2 more }` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `id: string` + - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` - The unique ID of the additional tools item. + 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. - - `role: "unknown" or "user" or "assistant" or 5 more` + - `"gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more` - The role that provided the additional tools. + 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. - - `"unknown"` + - `"gpt-5.6-sol"` - - `"user"` + - `"gpt-5.6-terra"` - - `"assistant"` + - `"gpt-5.6-luna"` - - `"system"` + - `"gpt-5.4"` - - `"critic"` + - `"gpt-5.4-mini"` - - `"discriminator"` + - `"gpt-5.4-nano"` - - `"developer"` + - `"gpt-5.4-mini-2026-03-17"` - - `"tool"` + - `"gpt-5.4-nano-2026-03-17"` - - `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.3-chat-latest"` - The additional tool definitions made available at this item. + - `"gpt-5.2"` - - `Function object { name, parameters, strict, 5 more }` + - `"gpt-5.2-2025-12-11"` - 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.2-chat-latest"` - - `name: string` + - `"gpt-5.2-pro"` - The name of the function to call. + - `"gpt-5.2-pro-2025-12-11"` - - `parameters: map[unknown]` + - `"gpt-5.1"` - A JSON schema object describing the parameters of the function. + - `"gpt-5.1-2025-11-13"` - - `strict: boolean` + - `"gpt-5.1-codex"` - Whether strict parameter validation is enforced for this function tool. + - `"gpt-5.1-mini"` - - `type: "function"` + - `"gpt-5.1-chat-latest"` - The type of the function tool. Always `function`. + - `"gpt-5"` - - `"function"` + - `"gpt-5-mini"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"gpt-5-nano"` - The tool invocation context(s). + - `"gpt-5-2025-08-07"` - - `"direct"` + - `"gpt-5-mini-2025-08-07"` - - `"programmatic"` + - `"gpt-5-nano-2025-08-07"` - - `defer_loading: optional boolean` + - `"gpt-5-chat-latest"` - Whether this function is deferred and loaded via tool search. + - `"gpt-4.1"` - - `description: optional string` + - `"gpt-4.1-mini"` - A description of the function. Used by the model to determine whether or not to call the function. + - `"gpt-4.1-nano"` - - `output_schema: optional map[unknown]` + - `"gpt-4.1-2025-04-14"` - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `"gpt-4.1-mini-2025-04-14"` - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + - `"gpt-4.1-nano-2025-04-14"` - 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). + - `"o4-mini"` - - `type: "file_search"` + - `"o4-mini-2025-04-16"` - The type of the file search tool. Always `file_search`. + - `"o3"` - - `"file_search"` + - `"o3-2025-04-16"` - - `vector_store_ids: array of string` + - `"o3-mini"` - The IDs of the vector stores to search. + - `"o3-mini-2025-01-31"` - - `filters: optional object { key, type, value } or object { filters, type }` + - `"o1"` - A filter to apply. + - `"o1-2024-12-17"` - - `ComparisonFilter object { key, type, value }` + - `"o1-preview"` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `"o1-preview-2024-09-12"` - - `key: string` + - `"o1-mini"` - The key to compare against the value. + - `"o1-mini-2024-09-12"` - - `type: "eq" or "ne" or "gt" or 5 more` + - `"gpt-4o"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `"gpt-4o-2024-11-20"` - - `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-4o-2024-08-06"` - - `"eq"` + - `"gpt-4o-2024-05-13"` - - `"ne"` + - `"gpt-4o-audio-preview"` - - `"gt"` + - `"gpt-4o-audio-preview-2024-10-01"` - - `"gte"` + - `"gpt-4o-audio-preview-2024-12-17"` - - `"lt"` + - `"gpt-4o-audio-preview-2025-06-03"` - - `"lte"` + - `"gpt-4o-mini-audio-preview"` - - `"in"` + - `"gpt-4o-mini-audio-preview-2024-12-17"` - - `"nin"` + - `"gpt-4o-search-preview"` - - `value: string or number or boolean or array of string or number` + - `"gpt-4o-mini-search-preview"` - The value to compare against the attribute key; supports string, number, or boolean types. + - `"gpt-4o-search-preview-2025-03-11"` - - `string` + - `"gpt-4o-mini-search-preview-2025-03-11"` - - `number` + - `"chatgpt-4o-latest"` - - `boolean` + - `"codex-mini-latest"` - - `array of string or number` + - `"gpt-4o-mini"` - - `string` + - `"gpt-4o-mini-2024-07-18"` - - `number` + - `"gpt-4-turbo"` - - `CompoundFilter object { filters, type }` + - `"gpt-4-turbo-2024-04-09"` - Combine multiple filters using `and` or `or`. + - `"gpt-4-0125-preview"` - - `filters: array of object { key, type, value } or unknown` + - `"gpt-4-turbo-preview"` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `"gpt-4-1106-preview"` - - `ComparisonFilter object { key, type, value }` + - `"gpt-4-vision-preview"` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `"gpt-4"` - - `key: string` + - `"gpt-4-0314"` - The key to compare against the value. + - `"gpt-4-0613"` - - `type: "eq" or "ne" or "gt" or 5 more` + - `"gpt-4-32k"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `"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"` - - `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-3.5-turbo-1106"` - - `"eq"` + - `"gpt-3.5-turbo-0125"` - - `"ne"` + - `"gpt-3.5-turbo-16k-0613"` - - `"gt"` + - `"o1-pro"` - - `"gte"` + - `"o1-pro-2025-03-19"` - - `"lt"` + - `"o3-pro"` - - `"lte"` + - `"o3-pro-2025-06-10"` - - `"in"` + - `"o3-deep-research"` - - `"nin"` + - `"o3-deep-research-2025-06-26"` - - `value: string or number or boolean or array of string or number` + - `"o4-mini-deep-research"` - The value to compare against the attribute key; supports string, number, or boolean types. + - `"o4-mini-deep-research-2025-06-26"` - - `string` + - `"computer-use-preview"` - - `number` + - `"computer-use-preview-2025-03-11"` - - `boolean` + - `"gpt-5-codex"` - - `array of string or number` + - `"gpt-5-pro"` - - `string` + - `"gpt-5-pro-2025-10-06"` - - `number` + - `"gpt-5.1-codex-max"` - - `unknown` + - `string` - - `type: "and" or "or"` + - `object: "response"` - Type of operation: `and` or `or`. + The object type of this resource - always set to `response`. - - `"and"` + - `"response"` - - `"or"` + - `output: array of BetaResponseOutputItem` - - `max_num_results: optional number` + An array of content items generated by the model. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - 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. - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `BetaResponseOutputMessage object { id, content, role, 4 more }` - Ranking options for search. + An output message from the model. - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `FileSearchCall object { id, queries, status, 3 more }` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + The results of a file search tool call. See the + [file search guide](/docs/guides/tools-file-search) for more information. - - `embedding_weight: number` + - `id: string` - The weight of the embedding in the reciprocal ranking fusion. + The unique ID of the file search tool call. - - `text_weight: number` + - `queries: array of string` - The weight of the text in the reciprocal ranking fusion. + The queries used to search for files. - - `ranker: optional "auto" or "default-2024-11-15"` + - `status: "in_progress" or "searching" or "completed" or 2 more` - The ranker to use for the file search. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `"auto"` + - `"in_progress"` - - `"default-2024-11-15"` + - `"searching"` - - `score_threshold: optional number` + - `"completed"` - 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. + - `"incomplete"` - - `Computer object { type }` + - `"failed"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `type: "file_search_call"` - - `type: "computer"` + The type of the file search tool call. Always `file_search_call`. - The type of the computer tool. Always `computer`. + - `"file_search_call"` - - `"computer"` + - `agent: optional object { agent_name }` - - `ComputerUsePreview object { display_height, display_width, environment, 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` - - `display_height: number` + The canonical name of the agent that produced this item. - The height of the computer display. + - `results: optional array of object { attributes, file_id, filename, 2 more }` - - `display_width: number` + The results of the file search tool call. - The width of the computer display. + - `attributes: optional map[string or number or boolean]` - - `environment: "windows" or "mac" or "linux" or 2 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. - The type of computer environment to control. + - `string` - - `"windows"` + - `number` - - `"mac"` + - `boolean` - - `"linux"` + - `file_id: optional string` - - `"ubuntu"` + The unique ID of the file. - - `"browser"` + - `filename: optional string` - - `type: "computer_use_preview"` + The name of the file. - The type of the computer use tool. Always `computer_use_preview`. + - `score: optional number` - - `"computer_use_preview"` + The relevance score of the file - a value between 0 and 1. - - `WebSearch object { type, filters, search_context_size, user_location }` + - `text: optional string` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The text that was retrieved from the file. - - `type: "web_search" or "web_search_2025_08_26"` + - `FunctionCall object { arguments, call_id, name, 6 more }` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. - - `"web_search"` + - `arguments: string` - - `"web_search_2025_08_26"` + A JSON string of the arguments to pass to the function. - - `filters: optional object { allowed_domains }` + - `call_id: string` - Filters for the search. + The unique ID of the function tool call generated by the model. - - `allowed_domains: optional array of string` + - `name: string` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + The name of the function to run. - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `type: "function_call"` - - `search_context_size: optional "low" or "medium" or "high"` + The type of the function tool call. Always `function_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. + - `"function_call"` - - `"low"` + - `id: optional string` - - `"medium"` + The unique ID of the function tool call. - - `"high"` + - `agent: optional object { agent_name }` - - `user_location: optional object { city, country, region, 2 more }` + The agent that produced this item. - 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`. + - `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` - - `type: optional "approximate"` + The call ID of the program item that produced this tool call. - The type of location approximation. Always `approximate`. + - `type: "program"` - - `"approximate"` + - `"program"` - - `Mcp object { server_label, type, allowed_callers, 9 more }` + - `namespace: optional string` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + The namespace of the function to run. - - `server_label: string` + - `status: optional "in_progress" or "completed" or "incomplete"` - A label for this MCP server, used to identify it in tool calls. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `type: "mcp"` + - `"in_progress"` - The type of the MCP tool. Always `mcp`. + - `"completed"` - - `"mcp"` + - `"incomplete"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `FunctionCallOutput object { id, call_id, output, 5 more }` - The tool invocation context(s). + - `id: string` - - `"direct"` + The unique ID of the function call tool output. - - `"programmatic"` + - `call_id: string` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + The unique ID of the function tool call generated by the model. - List of allowed tool names or a filter object. + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `McpAllowedTools = array of string` + The output from the function call generated by your code. + Can be a string or an list of output content. - A string array of allowed tool names + - `StringOutput = string` - - `McpToolFilter object { read_only, tool_names }` + A string of the output of the function call. - A filter object to specify which tools are allowed. + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `read_only: optional boolean` + Text, image, or file output of the function 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. + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `tool_names: optional array of string` + A text input to the model. - List of allowed tool names. + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `authorization: optional string` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - 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. + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + A file input to the model. - 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](https://platform.openai.com/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: "function_call_output"` - - `"connector_googledrive"` + The type of the function tool call output. Always `function_call_output`. - - `"connector_microsoftteams"` + - `"function_call_output"` - - `"connector_outlookcalendar"` + - `agent: optional object { agent_name }` - - `"connector_outlookemail"` + The agent that produced this item. - - `"connector_sharepoint"` + - `agent_name: string` - - `defer_loading: optional boolean` + The canonical name of the agent that produced this item. - Whether this MCP tool is deferred and discovered via tool search. + - `caller: optional object { type } or object { caller_id, type }` - - `headers: optional map[string]` + The execution context that produced this tool call. - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `Direct object { type }` - - `require_approval: optional object { always, never } or "always" or "never"` + - `type: "direct"` - Specify which of the MCP server's tools require approval. + The caller type. Always `direct`. - - `McpToolApprovalFilter object { always, never }` + - `"direct"` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `Program object { caller_id, type }` - - `always: optional 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. + The caller type. Always `program`. - - `tool_names: optional array of string` + - `"program"` - List of allowed tool names. + - `created_by: optional string` - - `never: optional object { read_only, tool_names }` + The identifier of the actor that created the item. - A filter object to specify which tools are allowed. + - `AgentMessage object { id, author, content, 3 more }` - - `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 agent message. - - `tool_names: optional array of string` + - `author: string` - List of allowed tool names. + The sending agent identity. - - `McpToolApprovalSetting = "always" or "never"` + - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 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. + Encrypted content sent between agents. - - `"always"` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `"never"` + A text input to the model. - - `server_description: optional string` + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - Optional description of the MCP server, used to provide more context. + A text output from the model. - - `server_url: optional string` + - `Text object { text, type }` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + A text content. - - `tunnel_id: optional string` + - `text: 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. + - `type: "text"` - - `CodeInterpreter object { container, type, allowed_callers }` + - `"text"` - A tool that runs Python code to help generate a response to a prompt. + - `SummaryText object { text, type }` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + A summary 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` + A summary of the reasoning output from the model so far. - The container ID. + - `type: "summary_text"` - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + The type of the object. Always `summary_text`. - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `"summary_text"` - - `type: "auto"` + - `ReasoningText object { text, type }` - Always `auto`. + Reasoning text from the model. - - `"auto"` + - `text: string` - - `file_ids: optional array of string` + The reasoning text from the model. - An optional list of uploaded files to make available to your code. + - `type: "reasoning_text"` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + The type of the reasoning text. Always `reasoning_text`. - The memory limit for the code interpreter container. + - `"reasoning_text"` - - `"1g"` + - `BetaResponseOutputRefusal object { refusal, type }` - - `"4g"` + A refusal from the model. - - `"16g"` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `"64g"` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` - Network access policy for the container. + A screenshot of a computer. - - `BetaContainerNetworkPolicyDisabled object { type }` + - `detail: "low" or "high" or "auto" or "original"` - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `type: "code_interpreter"` + - `"low"` - The type of the code interpreter tool. Always `code_interpreter`. + - `"high"` - - `"code_interpreter"` + - `"auto"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"original"` - The tool invocation context(s). + - `file_id: string` - - `"direct"` + The identifier of an uploaded file that contains the screenshot. - - `"programmatic"` + - `image_url: string` - - `ProgrammaticToolCalling object { type }` + The URL of the screenshot image. - - `type: "programmatic_tool_calling"` + - `type: "computer_screenshot"` - The type of the tool. Always `programmatic_tool_calling`. + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `"programmatic_tool_calling"` + - `"computer_screenshot"` - - `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"` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - Whether to generate a new image or edit an existing image. Default: `auto`. + A file input to the model. - - `"generate"` + - `EncryptedContent object { encrypted_content, type }` - - `"edit"` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `"auto"` + - `encrypted_content: string` - - `background: optional "transparent" or "opaque" or "auto"` + Opaque encrypted content. - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + - `type: "encrypted_content"` - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + The type of the input item. Always `encrypted_content`. - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `"encrypted_content"` - - `"transparent"` + - `recipient: string` - - `"opaque"` + The destination agent identity. - - `"auto"` + - `type: "agent_message"` - - `input_fidelity: optional "high" or "low"` + The type of the item. Always `agent_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`. + - `"agent_message"` - - `"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` + - `MultiAgentCall object { id, action, arguments, 3 more }` - File ID for the mask image. + - `id: string` - - `image_url: optional string` + The unique ID of the multi-agent call item. - Base64-encoded mask image. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + The multi-agent action to execute. - The image generation model to use. Default: `gpt-image-1`. + - `"spawn_agent"` - - `string` + - `"interrupt_agent"` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `"list_agents"` - The image generation model to use. Default: `gpt-image-1`. + - `"send_message"` - - `"gpt-image-1"` + - `"followup_task"` - - `"gpt-image-1-mini"` + - `"wait_agent"` - - `"gpt-image-2"` + - `arguments: string` - - `"gpt-image-2-2026-04-21"` + The JSON string of arguments generated for the action. - - `"gpt-image-1.5"` + - `call_id: string` - - `"chatgpt-image-latest"` + The unique ID linking this call to its output. - - `moderation: optional "auto" or "low"` + - `type: "multi_agent_call"` - Moderation level for the generated image. Default: `auto`. + The type of the multi-agent call. Always `multi_agent_call`. - - `"auto"` + - `"multi_agent_call"` - - `"low"` + - `agent: optional object { agent_name }` - - `output_compression: optional number` + The agent that produced this item. - Compression level for the output image. Default: 100. + - `agent_name: string` - - `output_format: optional "png" or "webp" or "jpeg"` + The canonical name of the agent that produced this item. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `MultiAgentCallOutput object { id, action, call_id, 3 more }` - - `"png"` + - `id: string` - - `"webp"` + The unique ID of the multi-agent call output item. - - `"jpeg"` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `partial_images: optional number` + The multi-agent action that produced this result. - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `"spawn_agent"` - - `quality: optional "low" or "medium" or "high" or "auto"` + - `"interrupt_agent"` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `"list_agents"` - - `"low"` + - `"send_message"` - - `"medium"` + - `"followup_task"` - - `"high"` + - `"wait_agent"` - - `"auto"` + - `call_id: string` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + The unique ID of the multi-agent 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`. + - `output: array of BetaResponseOutputText` - - `string` + Text output returned by the multi-agent action. - - `"1024x1024" or "1024x1536" or "1536x1024" or "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 }` - 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 annotations of the text output. - - `"1024x1024"` + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - - `"1024x1536"` + - `text: string` - - `"1536x1024"` + The text output from the model. - - `"auto"` + - `type: "output_text"` - - `LocalShell object { type }` + The type of the output text. Always `output_text`. - A tool that allows the model to execute shell commands in a local environment. + - `type: "multi_agent_call_output"` - - `type: "local_shell"` + The type of the multi-agent result. Always `multi_agent_call_output`. - The type of the local shell tool. Always `local_shell`. + - `"multi_agent_call_output"` - - `"local_shell"` + - `agent: optional object { agent_name }` - - `Shell object { type, allowed_callers, environment }` + The agent that produced this item. - A tool that allows the model to execute shell commands. + - `agent_name: string` - - `type: "shell"` + The canonical name of the agent that produced this item. - The type of the shell tool. Always `shell`. + - `WebSearchCall object { id, action, status, 2 more }` - - `"shell"` + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `id: string` - The tool invocation context(s). + The unique ID of the web search tool call. - - `"direct"` + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - - `"programmatic"` + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + - `Search object { type, queries, query, sources }` - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + Action type "search" - Performs a web search query. - - `BetaLocalEnvironment object { type, skills }` + - `type: "search"` - - `BetaContainerReference object { container_id, type }` + The action type. - - `Custom object { name, type, allowed_callers, 3 more }` + - `"search"` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `queries: optional array of string` - - `name: string` + The search queries. - The name of the custom tool, used to identify it in tool calls. + - `query: optional string` - - `type: "custom"` + The search query. - The type of the custom tool. Always `custom`. + - `sources: optional array of object { type, url }` - - `"custom"` + The sources used in the search. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `type: "url"` - The tool invocation context(s). + The type of source. Always `url`. - - `"direct"` + - `"url"` - - `"programmatic"` + - `url: string` - - `defer_loading: optional boolean` + The URL of the source. - Whether this tool should be deferred and discovered via tool search. + - `OpenPage object { type, url }` - - `description: optional string` + Action type "open_page" - Opens a specific URL from search results. - Optional description of the custom tool, used to provide more context. + - `type: "open_page"` - - `format: optional object { type } or object { definition, syntax, type }` + The action type. - The input format for the custom tool. Default is unconstrained text. + - `"open_page"` - - `Text object { type }` + - `url: optional string` - Unconstrained free-form text. + The URL opened by the model. - - `type: "text"` + - `FindInPage object { pattern, type, url }` - Unconstrained text format. Always `text`. + Action type "find_in_page": Searches for a pattern within a loaded page. - - `"text"` + - `pattern: string` - - `Grammar object { definition, syntax, type }` + The pattern or text to search for within the page. - A grammar defined by the user. + - `type: "find_in_page"` - - `definition: string` + The action type. - The grammar definition. + - `"find_in_page"` - - `syntax: "lark" or "regex"` + - `url: string` - The syntax of the grammar definition. One of `lark` or `regex`. + The URL of the page searched for the pattern. - - `"lark"` + - `status: "in_progress" or "searching" or "completed" or "failed"` - - `"regex"` + The status of the web search tool call. - - `type: "grammar"` + - `"in_progress"` - Grammar format. Always `grammar`. + - `"searching"` - - `"grammar"` + - `"completed"` - - `Namespace object { description, name, tools, type }` + - `"failed"` - Groups function/custom tools under a shared namespace. + - `type: "web_search_call"` - - `description: string` + The type of the web search tool call. Always `web_search_call`. - A description of the namespace shown to the model. + - `"web_search_call"` - - `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 }` + - `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. - - `type: "function"` + - `id: string` - - `"function"` + The unique ID of the computer call. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `call_id: string` - The tool invocation context(s). + An identifier used when responding to the tool call with output. - - `"direct"` + - `pending_safety_checks: array of object { id, code, message }` - - `"programmatic"` + The pending safety checks for the computer call. - - `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` + - `status: "in_progress" or "completed" or "incomplete"` - 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 status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `Custom object { name, type, allowed_callers, 3 more }` + - `"in_progress"` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `"completed"` - - `name: string` + - `"incomplete"` - The name of the custom tool, used to identify it in tool calls. + - `type: "computer_call"` - - `type: "custom"` + The type of the computer call. Always `computer_call`. - The type of the custom tool. Always `custom`. + - `"computer_call"` - - `"custom"` + - `action: optional BetaComputerAction` - - `allowed_callers: optional array of "direct" or "programmatic"` + A click action. - The tool invocation context(s). + - `actions: optional BetaComputerActionList` - - `"direct"` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `"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. + - `ComputerCallOutput object { id, call_id, output, 5 more }` - - `format: optional object { type } or object { definition, syntax, type }` + - `id: string` - The input format for the custom tool. Default is unconstrained text. + The unique ID of the computer call tool output. - - `Text object { type }` + - `call_id: string` - Unconstrained free-form text. + The ID of the computer tool call that produced the output. - - `type: "text"` + - `output: BetaResponseComputerToolCallOutputScreenshot` - Unconstrained text format. Always `text`. + A computer screenshot image used with the computer use tool. - - `"text"` + - `status: "completed" or "incomplete" or "failed" or "in_progress"` - - `Grammar object { definition, syntax, type }` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - A grammar defined by the user. + - `"completed"` - - `definition: string` + - `"incomplete"` - The grammar definition. + - `"failed"` - - `syntax: "lark" or "regex"` + - `"in_progress"` - The syntax of the grammar definition. One of `lark` or `regex`. + - `type: "computer_call_output"` - - `"lark"` + The type of the computer tool call output. Always `computer_call_output`. - - `"regex"` + - `"computer_call_output"` - - `type: "grammar"` + - `acknowledged_safety_checks: optional array of object { id, code, message }` - Grammar format. Always `grammar`. + The safety checks reported by the API that have been acknowledged by the + developer. - - `"grammar"` + - `id: string` - - `type: "namespace"` + The ID of the pending safety check. - The type of the tool. Always `namespace`. + - `code: optional string` - - `"namespace"` + The type of the pending safety check. - - `ToolSearch object { type, description, execution, parameters }` + - `message: optional string` - Hosted or BYOT tool search configuration for deferred tools. + Details about the pending safety check. - - `type: "tool_search"` + - `agent: optional object { agent_name }` - The type of the tool. Always `tool_search`. + The agent that produced this item. - - `"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. + - `created_by: optional string` - - `execution: optional "server" or "client"` + The identifier of the actor that created the item. - Whether tool search is executed by the server or by the client. + - `Reasoning object { id, summary, type, 4 more }` - - `"server"` + 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). - - `"client"` + - `id: string` - - `parameters: optional unknown` + The unique identifier of the reasoning content. - Parameter schema for a client-executed tool search tool. + - `summary: array of object { text, type }` - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + Reasoning summary content. - 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). + - `text: string` - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + A summary of the reasoning output from the model so far. - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `type: "summary_text"` - - `"web_search_preview"` + The type of the object. Always `summary_text`. - - `"web_search_preview_2025_03_11"` + - `"summary_text"` - - `search_content_types: optional array of "text" or "image"` + - `type: "reasoning"` - - `"text"` + The type of the object. Always `reasoning`. - - `"image"` + - `"reasoning"` - - `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"` + - `content: optional array of object { text, type }` - - `user_location: optional object { type, city, country, 2 more }` + Reasoning text content. - The user's location. + - `text: string` - - `type: "approximate"` + The reasoning text from the model. - The type of location approximation. Always `approximate`. + - `type: "reasoning_text"` - - `"approximate"` + The type of the reasoning text. Always `reasoning_text`. - - `city: optional string` + - `"reasoning_text"` - Free text input for the city of the user, e.g. `San Francisco`. + - `encrypted_content: optional string` - - `country: optional string` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `region: optional string` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Free text input for the region of the user, e.g. `California`. + - `"in_progress"` - - `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 }` + - `Program object { id, call_id, code, 3 more }` - Allows the assistant to create, delete, or update files using unified diffs. + - `id: string` - - `type: "apply_patch"` + The unique ID of the program item. - The type of the tool. Always `apply_patch`. + - `call_id: string` - - `"apply_patch"` + The stable call ID of the program item. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `code: string` - The tool invocation context(s). + The JavaScript source executed by programmatic tool calling. - - `"direct"` + - `fingerprint: string` - - `"programmatic"` + Opaque program replay fingerprint that must be round-tripped. - - `type: "additional_tools"` + - `type: "program"` - The type of the item. Always `additional_tools`. + The type of the item. Always `program`. - - `"additional_tools"` + - `"program"` - `agent: optional object { agent_name }` @@ -85486,23 +84428,33 @@ 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](https://platform.openai.com/docs/api-reference/responses/compact). + - `ProgramOutput object { id, call_id, result, 3 more }` - `id: string` - The unique ID of the compaction item. + The unique ID of the program output item. - - `encrypted_content: string` + - `call_id: string` - The encrypted content that was produced by compaction. + The call ID of the program item. - - `type: "compaction"` + - `result: string` - The type of the item. Always `compaction`. + The result produced by the program item. - - `"compaction"` + - `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 }` @@ -85512,39 +84464,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` + - `ToolSearchCall object { id, arguments, call_id, 5 more }` - The identifier of the actor that created the item. + - `id: string` - - `ImageGenerationCall object { id, result, status, 2 more }` + The unique ID of the tool search call item. - An image generation request made by the model. + - `arguments: unknown` - - `id: string` + Arguments used for the tool search call. - The unique ID of the image generation call. + - `call_id: string` - - `result: string` + The unique ID of the tool search call generated by the model. - The generated image encoded in base64. + - `execution: "server" or "client"` - - `status: "in_progress" or "completed" or "generating" or "failed"` + Whether tool search was executed by the server or by the client. - The status of the image generation call. + - `"server"` + + - `"client"` + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the tool search call item that was recorded. - `"in_progress"` - `"completed"` - - `"generating"` - - - `"failed"` + - `"incomplete"` - - `type: "image_generation_call"` + - `type: "tool_search_call"` - The type of the image generation call. Always `image_generation_call`. + The type of the item. Always `tool_search_call`. - - `"image_generation_call"` + - `"tool_search_call"` - `agent: optional object { agent_name }` @@ -85554,1090 +84510,1078 @@ 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. + - `created_by: optional string` - - `outputs: array of object { logs, type } or object { type, url }` + The identifier of the actor that created the item. - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `ToolSearchOutput object { id, call_id, execution, 5 more }` - - `Logs object { logs, type }` + - `id: string` - The logs output from the code interpreter. + The unique ID of the tool search output item. - - `logs: string` + - `call_id: string` - The logs output from the code interpreter. + The unique ID of the tool search call generated by the model. - - `type: "logs"` + - `execution: "server" or "client"` - The type of the output. Always `logs`. + Whether tool search was executed by the server or by the client. - - `"logs"` + - `"server"` - - `Image object { type, url }` + - `"client"` - The image output from the code interpreter. + - `status: "in_progress" or "completed" or "incomplete"` - - `type: "image"` + The status of the tool search output item that was recorded. - The type of the output. Always `image`. + - `"in_progress"` - - `"image"` + - `"completed"` - - `url: string` + - `"incomplete"` - The URL of the image output from the code interpreter. + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + The loaded tool definitions returned by tool search. - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `Function object { name, parameters, strict, 5 more }` - - `"in_progress"` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `"completed"` + - `name: string` - - `"incomplete"` + The name of the function to call. - - `"interpreting"` + - `parameters: map[unknown]` - - `"failed"` + A JSON schema object describing the parameters of the function. - - `type: "code_interpreter_call"` + - `strict: boolean` - The type of the code interpreter tool call. Always `code_interpreter_call`. + Whether strict parameter validation is enforced for this function tool. - - `"code_interpreter_call"` + - `type: "function"` - - `agent: optional object { agent_name }` + The type of the function tool. Always `function`. - The agent that produced this item. + - `"function"` - - `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` + - `defer_loading: optional boolean` - The unique ID of the local shell call. + Whether this function is deferred and loaded via tool search. - - `action: object { command, env, type, 3 more }` + - `description: optional string` - Execute a shell command on the server. + A description of the function. Used by the model to determine whether or not to call the function. - - `command: array of string` + - `output_schema: optional map[unknown]` - The command to run. + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `env: map[string]` + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - Environment variables to set for the command. + 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: "exec"` + - `type: "file_search"` - The type of the local shell action. Always `exec`. + The type of the file search tool. Always `file_search`. - - `"exec"` + - `"file_search"` - - `timeout_ms: optional number` + - `vector_store_ids: array of string` - Optional timeout in milliseconds for the command. + The IDs of the vector stores to search. - - `user: optional string` + - `filters: optional object { key, type, value } or object { filters, type }` - Optional user to run the command as. + A filter to apply. - - `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`. + - `CompoundFilter object { filters, type }` - - `"local_shell_call_output"` + Combine multiple filters using `and` or `or`. - - `agent: optional object { agent_name }` + - `filters: array of object { key, type, value } or unknown` - The agent that produced this item. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `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 { id, action, call_id, 6 more }` + - `"eq"` - A tool call that executes one or more shell commands in a managed environment. + - `"ne"` - - `id: string` + - `"gt"` - The unique ID of the shell tool call. Populated when this item is returned via API. + - `"gte"` - - `action: object { commands, max_output_length, timeout_ms }` + - `"lt"` - The shell commands and limits that describe how to run the tool call. + - `"lte"` - - `commands: array of string` + - `"in"` - - `max_output_length: number` + - `"nin"` - Optional maximum number of characters to return from each command. + - `value: string or number or boolean or array of string or number` - - `timeout_ms: number` + The value to compare against the attribute key; supports string, number, or boolean types. - Optional timeout in milliseconds for the commands. + - `string` - - `call_id: string` + - `number` - The unique ID of the shell tool call generated by the model. + - `boolean` - - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` + - `array of string or number` - Represents the use of a local environment to perform shell actions. + - `string` - - `BetaResponseLocalEnvironment object { type }` + - `number` - Represents the use of a local environment to perform shell actions. + - `unknown` - - `type: "local"` + - `type: "and" or "or"` - The environment type. Always `local`. + Type of operation: `and` or `or`. - - `"local"` + - `"and"` - - `BetaResponseContainerReference object { container_id, type }` + - `"or"` - Represents a container created with /v1/containers. + - `max_num_results: optional number` - - `container_id: string` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `type: "container_reference"` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - The environment type. Always `container_reference`. + Ranking options for search. - - `"container_reference"` + - `hybrid_search: optional object { embedding_weight, text_weight }` - - `status: "in_progress" or "completed" or "incomplete"` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `embedding_weight: number` - - `"in_progress"` + 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. - - `type: "shell_call"` + - `ranker: optional "auto" or "default-2024-11-15"` - The type of the item. Always `shell_call`. + The ranker to use for the file search. - - `"shell_call"` + - `"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 }` - - `caller: optional object { type } or 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). - The execution context that produced this tool call. + - `type: "computer"` - - `Direct object { type }` + The type of the computer tool. Always `computer`. - - `type: "direct"` + - `"computer"` - - `"direct"` + - `ComputerUsePreview object { display_height, display_width, environment, 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` + - `display_height: number` - The call ID of the program item that produced this tool call. + The height of the computer display. - - `type: "program"` + - `display_width: number` - - `"program"` + The width of the computer display. - - `created_by: optional string` + - `environment: "windows" or "mac" or "linux" or 2 more` - The ID of the entity that created this tool call. + The type of computer environment to control. - - `ShellCallOutput object { id, call_id, max_output_length, 6 more }` + - `"windows"` - The output of a shell tool call that was emitted. + - `"mac"` - - `id: string` + - `"linux"` - The unique ID of the shell call output. Populated when this item is returned via API. + - `"ubuntu"` - - `call_id: string` + - `"browser"` - The unique ID of the shell tool call generated by the model. + - `type: "computer_use_preview"` - - `max_output_length: number` + The type of the computer use tool. Always `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. + - `"computer_use_preview"` - - `output: array of object { outcome, stderr, stdout, created_by }` + - `WebSearch object { type, filters, search_context_size, user_location }` - An array of shell call output contents + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - - `outcome: object { type } or object { exit_code, type }` + - `type: "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. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `Timeout object { type }` + - `"web_search"` - Indicates that the shell call exceeded its configured time limit. + - `"web_search_2025_08_26"` - - `type: "timeout"` + - `filters: optional object { allowed_domains }` - The outcome type. Always `timeout`. + Filters for the search. - - `"timeout"` + - `allowed_domains: optional array of string` - - `Exit object { exit_code, type }` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - Indicates that the shell commands finished and returned an exit code. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `exit_code: number` + - `search_context_size: optional "low" or "medium" or "high"` - Exit code from the shell process. + 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: "exit"` + - `"low"` - The outcome type. Always `exit`. + - `"medium"` - - `"exit"` + - `"high"` - - `stderr: string` + - `user_location: optional object { city, country, region, 2 more }` - The standard error output that was captured. + The approximate location of the user. - - `stdout: string` + - `city: optional string` - The standard output that was captured. + Free text input for the city of the user, e.g. `San Francisco`. - - `created_by: optional string` + - `country: optional string` - The identifier of the actor that created the item. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `status: "in_progress" or "completed" or "incomplete"` + - `region: optional string` - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + Free text input for the region of the user, e.g. `California`. - - `"in_progress"` + - `timezone: optional string` - - `"completed"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `"incomplete"` + - `type: optional "approximate"` - - `type: "shell_call_output"` + The type of location approximation. Always `approximate`. - The type of the shell call output. Always `shell_call_output`. + - `"approximate"` - - `"shell_call_output"` + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `agent: optional object { agent_name }` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - The agent that produced this item. + - `server_label: string` - - `agent_name: string` + A label for this MCP server, used to identify it in tool calls. - The canonical name of the agent that produced this item. + - `type: "mcp"` - - `caller: optional object { type } or object { caller_id, type }` + The type of the MCP tool. Always `mcp`. - The execution context that produced this tool call. + - `"mcp"` - - `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` + - `"programmatic"` - The call ID of the program item that produced this tool call. + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `type: "program"` + List of allowed tool names or a filter object. - - `"program"` + - `McpAllowedTools = array of string` - - `created_by: optional string` + A string array of allowed tool names - The identifier of the actor that created the item. + - `McpToolFilter object { read_only, tool_names }` - - `ApplyPatchCall object { id, call_id, operation, 5 more }` + A filter object to specify which tools are allowed. - A tool call that applies file diffs by creating, deleting, or updating files. + - `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 apply patch tool call. Populated when this item is returned via API. + - `tool_names: optional array of string` - - `call_id: string` + List of allowed tool names. - The unique ID of the apply patch tool call generated by the model. + - `authorization: optional string` - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, 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. - One of the create_file, delete_file, or update_file operations applied via apply_patch. + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `CreateFile 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). - Instruction describing how to create a file via the apply_patch tool. + Currently supported `connector_id` values are: - - `diff: 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` - Diff to apply. + - `"connector_dropbox"` - - `path: string` + - `"connector_gmail"` - Path of the file to create. + - `"connector_googlecalendar"` - - `type: "create_file"` + - `"connector_googledrive"` - Create a new file with the provided diff. + - `"connector_microsoftteams"` - - `"create_file"` + - `"connector_outlookcalendar"` - - `DeleteFile object { path, type }` + - `"connector_outlookemail"` - Instruction describing how to delete a file via the apply_patch tool. + - `"connector_sharepoint"` - - `path: string` + - `defer_loading: optional boolean` - Path of the file to delete. + Whether this MCP tool is deferred and discovered via tool search. - - `type: "delete_file"` + - `headers: optional map[string]` - Delete the specified file. + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `"delete_file"` + - `require_approval: optional object { always, never } or "always" or "never"` - - `UpdateFile object { diff, path, type }` + Specify which of the MCP server's tools require approval. - Instruction describing how to update a 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. - Diff to apply. + - `always: optional object { read_only, tool_names }` - - `path: string` + A filter object to specify which tools are allowed. - Path of the file to update. + - `read_only: optional boolean` - - `type: "update_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. - Update an existing file with the provided diff. + - `tool_names: optional array of string` - - `"update_file"` + List of allowed tool names. - - `status: "in_progress" or "completed"` + - `never: optional object { read_only, tool_names }` - The status of the apply patch tool call. One of `in_progress` or `completed`. + 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. - - `type: "apply_patch_call"` + - `tool_names: optional array of string` - The type of the item. Always `apply_patch_call`. + List of allowed tool names. - - `"apply_patch_call"` + - `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` - - `"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. - - `Program object { caller_id, type }` + - `CodeInterpreter object { container, type, allowed_callers }` - - `caller_id: string` + A tool that runs Python code to help generate a response to a prompt. - The call ID of the program item that produced this tool call. + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `type: "program"` + 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. - - `"program"` + - `string` - - `created_by: optional string` + The container ID. - The ID of the entity that created this tool call. + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - - `ApplyPatchCallOutput object { id, call_id, status, 5 more }` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - The output emitted by an apply patch tool call. + - `type: "auto"` - - `id: string` + Always `auto`. - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `"auto"` - - `call_id: string` + - `file_ids: optional array of string` - The unique ID of the apply patch tool call generated by the model. + An optional list of uploaded files to make available to your code. - - `status: "completed" or "failed"` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - The status of the apply patch tool call output. One of `completed` or `failed`. + The memory limit for the code interpreter container. - - `"completed"` + - `"1g"` - - `"failed"` + - `"4g"` - - `type: "apply_patch_call_output"` + - `"16g"` - The type of the item. Always `apply_patch_call_output`. + - `"64g"` - - `"apply_patch_call_output"` + - `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 }` - - - `caller_id: string` - - The call ID of the program item that produced this tool call. + - `"programmatic"` - - `type: "program"` + - `ProgrammaticToolCalling object { type }` - - `"program"` + - `type: "programmatic_tool_calling"` - - `created_by: optional string` + The type of the tool. Always `programmatic_tool_calling`. - The ID of the entity that created this tool call output. + - `"programmatic_tool_calling"` - - `output: optional string` + - `ImageGeneration object { type, action, background, 9 more }` - Optional textual output returned by the apply patch tool. + A tool that generates images using the GPT image models. - - `McpCall object { id, arguments, name, 7 more }` + - `type: "image_generation"` - An invocation of a tool on an MCP server. + The type of the image generation tool. Always `image_generation`. - - `id: string` + - `"image_generation"` - The unique ID of the tool call. + - `action: optional "generate" or "edit" or "auto"` - - `arguments: string` + Whether to generate a new image or edit an existing image. Default: `auto`. - A JSON string of the arguments passed to the tool. + - `"generate"` - - `name: string` + - `"edit"` - The name of the tool that was run. + - `"auto"` - - `server_label: string` + - `background: optional "transparent" or "opaque" or "auto"` - The label of the MCP server running the tool. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - - `type: "mcp_call"` + - `"transparent"` - The type of the item. Always `mcp_call`. + - `"opaque"` - - `"mcp_call"` + - `"auto"` - - `agent: optional object { agent_name }` + - `input_fidelity: optional "high" or "low"` - 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`. - - `agent_name: string` + - `"high"` - The canonical name of the agent that produced this item. + - `"low"` - - `approval_request_id: optional string` + - `input_image_mask: optional object { file_id, image_url }` - 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. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `error: optional string` + - `file_id: optional string` - The error from the tool call, if any. + File ID for the mask image. - - `output: optional string` + - `image_url: optional string` - The output from the tool call. + Base64-encoded mask image. - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `model: optional string or "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"` + - `string` - - `"completed"` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `"incomplete"` + The image generation model to use. Default: `gpt-image-1`. - - `"calling"` + - `"gpt-image-1"` - - `"failed"` + - `"gpt-image-1-mini"` - - `McpListTools object { id, server_label, tools, 3 more }` + - `"gpt-image-1.5"` - A list of tools available on an MCP server. + - `moderation: optional "auto" or "low"` - - `id: string` + Moderation level for the generated image. Default: `auto`. - The unique ID of the list. + - `"auto"` - - `server_label: string` + - `"low"` - The label of the MCP server. + - `output_compression: optional number` - - `tools: array of object { input_schema, name, annotations, description }` + Compression level for the output image. Default: 100. - The tools available on the server. + - `output_format: optional "png" or "webp" or "jpeg"` - - `input_schema: unknown` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - The JSON schema describing the tool's input. + - `"png"` - - `name: string` + - `"webp"` - The name of the tool. + - `"jpeg"` - - `annotations: optional unknown` + - `partial_images: optional number` - Additional annotations about the tool. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `description: optional string` + - `quality: optional "low" or "medium" or "high" or "auto"` - The description of the tool. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `type: "mcp_list_tools"` + - `"low"` - The type of the item. Always `mcp_list_tools`. + - `"medium"` - - `"mcp_list_tools"` + - `"high"` - - `agent: optional object { agent_name }` + - `"auto"` - The agent that produced this item. + - `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` - - `error: optional string` + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - Error message if the server could not 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`. - - `McpApprovalRequest object { id, arguments, name, 3 more }` + - `"1024x1024"` - A request for human approval of a tool invocation. + - `"1024x1536"` - - `id: string` + - `"1536x1024"` - The unique ID of the approval request. + - `"auto"` - - `arguments: string` + - `LocalShell object { type }` - A JSON string of arguments for the tool. + A tool that allows the model to execute shell commands in a local environment. - - `name: string` + - `type: "local_shell"` - The name of the tool to run. + The type of the local shell tool. Always `local_shell`. - - `server_label: string` + - `"local_shell"` - The label of the MCP server making the request. + - `Shell object { type, allowed_callers, environment }` - - `type: "mcp_approval_request"` + A tool that allows the model to execute shell commands. - The type of the item. Always `mcp_approval_request`. + - `type: "shell"` - - `"mcp_approval_request"` + The type of the shell tool. Always `shell`. - - `agent: optional object { agent_name }` + - `"shell"` - 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"` - - `McpApprovalResponse object { id, approval_request_id, approve, 3 more }` + - `"programmatic"` - A response to an MCP approval request. + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - `id: string` + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - The unique ID of the approval response + - `BetaLocalEnvironment object { type, skills }` - - `approval_request_id: string` + - `BetaContainerReference object { container_id, type }` - The ID of the approval request being answered. + - `Custom object { name, type, allowed_callers, 3 more }` - - `approve: boolean` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - Whether the request was approved. + - `name: string` - - `type: "mcp_approval_response"` + The name of the custom tool, used to identify it in tool calls. - The type of the item. Always `mcp_approval_response`. + - `type: "custom"` - - `"mcp_approval_response"` + 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"` - - `reason: optional string` + - `"programmatic"` - Optional reason for the decision. + - `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"` + - `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` - - `"program"` + The namespace name used in tool calls (for example, `crm`). - - `namespace: optional string` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - The namespace of the custom tool being called. + The function/custom tools available inside this namespace. - - `CustomToolCallOutput object { id, call_id, output, 5 more }` + - `Function object { name, type, allowed_callers, 5 more }` - - `id: string` + - `name: string` - The unique ID of the custom tool call output item. + - `type: "function"` - - `call_id: string` + - `"function"` - The call ID, used to map this custom tool call output to a custom tool call. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + The tool invocation context(s). - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `"direct"` - - `StringOutput = string` + - `"programmatic"` - A string of the output of the custom tool call. + - `defer_loading: optional boolean` - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + Whether this function should be deferred and discovered via tool search. - Text, image, or file output of the custom tool call. + - `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](https://platform.openai.com/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 }` - - `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: "custom_tool_call_output"` + - `"custom"` - The type of the custom tool call output. Always `custom_tool_call_output`. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"custom_tool_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"` - - `parallel_tool_calls: boolean` + The syntax of the grammar definition. One of `lark` or `regex`. - Whether to allow the model to run tool calls in parallel. + - `"lark"` - - `temperature: number` + - `"regex"` - 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: "grammar"` - - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` + Grammar format. Always `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. + - `"grammar"` - - `BetaToolChoiceOptions = "none" or "auto" or "required"` + - `type: "namespace"` - Controls which (if any) tool is called by the model. + The type of the tool. Always `namespace`. - `none` means the model will not call any tool and instead generates a message. + - `"namespace"` - `auto` means the model can pick between generating a message or calling one or - more tools. + - `ToolSearch object { type, description, execution, parameters }` - `required` means the model must call one or more tools. + Hosted or BYOT tool search configuration for deferred tools. - - `"none"` + - `type: "tool_search"` - - `"auto"` + The type of the tool. Always `tool_search`. - - `"required"` + - `"tool_search"` - - `BetaToolChoiceAllowed object { mode, tools, type }` + - `description: optional string` - Constrains the tools available to the model to a pre-defined set. + Description shown to the model for a client-executed tool search tool. - - `mode: "auto" or "required"` + - `execution: optional "server" or "client"` - Constrains the tools available to the model to a pre-defined set. + Whether tool search is executed by the server or by the client. - `auto` allows the model to pick from among the allowed tools and generate a - message. + - `"server"` - `required` requires the model to call one or more of the allowed tools. + - `"client"` - - `"auto"` + - `parameters: optional unknown` - - `"required"` + Parameter schema for a client-executed tool search tool. - - `tools: array of map[unknown]` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - A list of tool definitions that the model should be allowed to 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). - For the Responses API, the list of tool definitions might look like: + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `type: "allowed_tools"` + - `"web_search_preview"` - Allowed tool configuration type. Always `allowed_tools`. + - `"web_search_preview_2025_03_11"` - - `"allowed_tools"` + - `search_content_types: optional array of "text" or "image"` - - `BetaToolChoiceTypes object { type }` + - `"text"` - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + - `"image"` - - `type: "file_search" or "web_search_preview" or "computer" or 5 more` + - `search_context_size: optional "low" or "medium" or "high"` - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + 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. - Allowed values are: + - `"low"` - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + - `"medium"` - - `"file_search"` + - `"high"` - - `"web_search_preview"` + - `user_location: optional object { type, city, country, 2 more }` - - `"computer"` + The user's location. - - `"computer_use_preview"` + - `type: "approximate"` - - `"computer_use"` + The type of location approximation. Always `approximate`. - - `"web_search_preview_2025_03_11"` + - `"approximate"` - - `"image_generation"` + - `city: optional string` - - `"code_interpreter"` + Free text input for the city of the user, e.g. `San Francisco`. - - `BetaToolChoiceFunction object { name, type }` + - `country: optional string` - Use this option to force the model to call a specific function. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `name: string` + - `region: optional string` - The name of the function to call. + Free text input for the region of the user, e.g. `California`. - - `type: "function"` + - `timezone: optional string` - For function calling, the type is always `function`. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `"function"` + - `ApplyPatch object { type, allowed_callers }` - - `BetaToolChoiceMcp object { server_label, type, name }` + Allows the assistant to create, delete, or update files using unified diffs. - Use this option to force the model to call a specific tool on a remote MCP server. + - `type: "apply_patch"` - - `server_label: string` + The type of the tool. Always `apply_patch`. - The label of the MCP server to use. + - `"apply_patch"` - - `type: "mcp"` + - `allowed_callers: optional array of "direct" or "programmatic"` - For MCP tools, the type is always `mcp`. + The tool invocation context(s). - - `"mcp"` + - `"direct"` - - `name: optional string` + - `"programmatic"` - The name of the tool to call on the server. + - `type: "tool_search_output"` - - `BetaToolChoiceCustom object { name, type }` + The type of the item. Always `tool_search_output`. - Use this option to force the model to call a specific custom tool. + - `"tool_search_output"` - - `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"` + - `created_by: optional string` - - `BetaSpecificProgrammaticToolCallingParam object { type }` + The identifier of the actor that created the item. - - `type: "programmatic_tool_calling"` + - `AdditionalTools object { id, role, tools, 2 more }` - The tool to call. Always `programmatic_tool_calling`. + - `id: string` - - `"programmatic_tool_calling"` + The unique ID of the additional tools item. - - `BetaToolChoiceApplyPatch object { type }` + - `role: "unknown" or "user" or "assistant" or 5 more` - Forces the model to call the apply_patch tool when executing a tool call. + The role that provided the additional tools. - - `type: "apply_patch"` + - `"unknown"` - The tool to call. Always `apply_patch`. + - `"user"` - - `"apply_patch"` + - `"assistant"` - - `BetaToolChoiceShell object { type }` + - `"system"` - Forces the model to call the shell tool when a tool call is required. + - `"critic"` - - `type: "shell"` + - `"discriminator"` - The tool to call. Always `shell`. + - `"developer"` - - `"shell"` + - `"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` - 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](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/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](https://platform.openai.com/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](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. + The additional tool definitions made available at this item. - `Function object { name, parameters, strict, 5 more }` @@ -86900,7 +85844,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-web-search). + [web search tool](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -86960,7 +85904,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -87012,7 +85956,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -87204,19 +86148,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `background: optional "transparent" or "opaque" or "auto"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. - - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. - - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - `"transparent"` @@ -87245,13 +86178,13 @@ curl -X POST https://api.openai.com/v1/responses/compact \ Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `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-2" or 3 more` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` The image generation model to use. Default: `gpt-image-1`. @@ -87259,14 +86192,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"gpt-image-1-mini"` - - `"gpt-image-2"` - - - `"gpt-image-2-2026-04-21"` - - `"gpt-image-1.5"` - - `"chatgpt-image-latest"` - - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -87363,7 +86290,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -87477,7 +86404,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -87645,5603 +86572,5592 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"programmatic"` - - `top_p: number` + - `type: "additional_tools"` - An alternative to sampling with temperature, called nucleus sampling, - where the model considers the results of the tokens with top_p probability - mass. So 0.1 means only the tokens comprising the top 10% probability mass - are considered. + The type of the item. Always `additional_tools`. - We generally recommend altering this or `temperature` but not both. + - `"additional_tools"` - - `background: optional boolean` + - `agent: optional object { agent_name }` - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + The agent that produced this item. - - `completed_at: optional number` + - `agent_name: string` - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + The canonical name of the agent that produced this item. - - `conversation: optional object { id }` + - `Compaction object { id, encrypted_content, type, 2 more }` - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). - `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](https://platform.openai.com/docs/guides/reasoning). - - - `max_tool_calls: optional number` + The unique ID of the compaction item. - 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. + - `encrypted_content: string` - - `moderation: optional object { input, output }` + The encrypted content that was produced by compaction. - Moderation results for the response input and output, if moderated completions were requested. + - `type: "compaction"` - - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + The type of the item. Always `compaction`. - Moderation for the response input. + - `"compaction"` - - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` + - `agent: optional object { agent_name }` - A moderation result produced for the response input or output. + The agent that produced this item. - - `categories: map[boolean]` + - `agent_name: string` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + The canonical name of the agent that produced this item. - - `category_applied_input_types: map[array of "text" or "image"]` + - `created_by: optional string` - Which modalities of input are reflected by the score for each category. + The identifier of the actor that created the item. - - `"text"` + - `ImageGenerationCall object { id, result, status, 2 more }` - - `"image"` + An image generation request made by the model. - - `category_scores: map[number]` + - `id: string` - A dictionary of moderation categories to scores. + The unique ID of the image generation call. - - `flagged: boolean` + - `result: string` - A boolean indicating whether the content was flagged by any category. + The generated image encoded in base64. - - `model: string` + - `status: "in_progress" or "completed" or "generating" or "failed"` - The moderation model that produced this result. + The status of the image generation call. - - `type: "moderation_result"` + - `"in_progress"` - The object type, which was always `moderation_result` for successful moderation results. + - `"completed"` - - `"moderation_result"` + - `"generating"` - - `Error object { code, message, type }` + - `"failed"` - An error produced while attempting moderation for the response input or output. + - `type: "image_generation_call"` - - `code: string` + The type of the image generation call. Always `image_generation_call`. - The error code. + - `"image_generation_call"` - - `message: string` + - `agent: optional object { agent_name }` - The error message. + The agent that produced this item. - - `type: "error"` + - `agent_name: string` - The object type, which was always `error` for moderation failures. + The canonical name of the agent that produced this item. - - `"error"` + - `CodeInterpreterCall object { id, code, container_id, 4 more }` - - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + A tool call to run code. - Moderation for the response output. + - `id: string` - - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` + The unique ID of the code interpreter tool call. - A moderation result produced for the response input or output. + - `code: string` - - `categories: map[boolean]` + The code to run, or null if not available. - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `container_id: string` - - `category_applied_input_types: map[array of "text" or "image"]` + The ID of the container used to run the code. - Which modalities of input are reflected by the score for each category. + - `outputs: array of object { logs, type } or object { type, url }` - - `"text"` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `"image"` + - `Logs object { logs, type }` - - `category_scores: map[number]` + The logs output from the code interpreter. - A dictionary of moderation categories to scores. + - `logs: string` - - `flagged: boolean` + The logs output from the code interpreter. - A boolean indicating whether the content was flagged by any category. + - `type: "logs"` - - `model: string` + The type of the output. Always `logs`. - The moderation model that produced this result. + - `"logs"` - - `type: "moderation_result"` + - `Image object { type, url }` - The object type, which was always `moderation_result` for successful moderation results. + The image output from the code interpreter. - - `"moderation_result"` + - `type: "image"` - - `Error object { code, message, type }` + The type of the output. Always `image`. - An error produced while attempting moderation for the response input or output. + - `"image"` - - `code: string` + - `url: string` - The error code. + The URL of the image output from the code interpreter. - - `message: string` + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - The error message. + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `type: "error"` + - `"in_progress"` - The object type, which was always `error` for moderation failures. + - `"completed"` - - `"error"` + - `"incomplete"` - - `previous_response_id: optional string` + - `"interpreting"` - The unique ID of the previous response to the model. Use this to - create multi-turn conversations. Learn more about - [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + - `"failed"` - - `prompt: optional BetaResponsePrompt` + - `type: "code_interpreter_call"` - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `id: string` + - `"code_interpreter_call"` - The unique identifier of the prompt template to use. + - `agent: optional object { agent_name }` - - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` + The agent that produced this item. - 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. + - `agent_name: string` - - `string` + The canonical name of the agent that produced this item. - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `LocalShellCall object { id, action, call_id, 3 more }` - A text input to the model. + A tool call to run a command on the local shell. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `id: string` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The unique ID of the local shell call. - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `action: object { command, env, type, 3 more }` - A file input to the model. + Execute a shell command on the server. - - `version: optional string` + - `command: array of string` - Optional version of the prompt template. + The command to run. - - `prompt_cache_key: optional string` + - `env: map[string]` - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + Environment variables to set for the command. - - `prompt_cache_options: optional object { mode, ttl }` + - `type: "exec"` - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + The type of the local shell action. Always `exec`. - - `mode: "implicit" or "explicit"` + - `"exec"` - Whether implicit prompt-cache breakpoints were enabled. + - `timeout_ms: optional number` - - `"implicit"` + Optional timeout in milliseconds for the command. - - `"explicit"` + - `user: optional string` - - `ttl: "30m"` + Optional user to run the command as. - The minimum lifetime applied to each cache breakpoint. + - `working_directory: optional string` - - `"30m"` + Optional working directory to run the command in. - - `prompt_cache_retention: optional "in_memory" or "24h"` + - `call_id: string` - Deprecated. Use `prompt_cache_options.ttl` instead. + The unique ID of the local shell tool call generated by 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](https://platform.openai.com/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. + - `status: "in_progress" or "completed" or "incomplete"` - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + The status of the local shell call. - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `"in_progress"` - - `"in_memory"` + - `"completed"` - - `"24h"` + - `"incomplete"` - - `reasoning: optional object { context, effort, generate_summary, 2 more }` + - `type: "local_shell_call"` - **gpt-5 and o-series models only** + The type of the local shell call. Always `local_shell_call`. - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + - `"local_shell_call"` - - `context: optional "auto" or "current_turn" or "all_turns"` + - `agent: optional object { agent_name }` - Controls which reasoning items are rendered back to the model on later turns. - When returned on a response, this is the effective reasoning context mode - used for the response. + The agent that produced this item. - - `"auto"` + - `agent_name: string` - - `"current_turn"` + The canonical name of the agent that produced this item. - - `"all_turns"` + - `LocalShellCallOutput object { id, output, type, 2 more }` - - `effort: optional "none" or "minimal" or "low" or 4 more` + The output of a local shell tool call. - 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. + - `id: string` - - `"none"` + The unique ID of the local shell tool call generated by the model. - - `"minimal"` + - `output: string` - - `"low"` + A JSON string of the output of the local shell tool call. - - `"medium"` + - `type: "local_shell_call_output"` - - `"high"` + The type of the local shell tool call output. Always `local_shell_call_output`. - - `"xhigh"` + - `"local_shell_call_output"` - - `"max"` + - `agent: optional object { agent_name }` - - `generate_summary: optional "auto" or "concise" or "detailed"` + The agent that produced this item. - **Deprecated:** use `summary` instead. + - `agent_name: 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 canonical name of the agent that produced this item. - - `"auto"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"concise"` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `"detailed"` + - `"in_progress"` - - `mode: optional string or "standard" or "pro"` + - `"completed"` - Controls the reasoning execution mode for the request. + - `"incomplete"` - When returned on a response, this is the effective execution mode. + - `ShellCall object { id, action, call_id, 6 more }` - - `string` + A tool call that executes one or more shell commands in a managed environment. - - `"standard" or "pro"` + - `id: string` - Controls the reasoning execution mode for the request. + The unique ID of the shell tool call. Populated when this item is returned via API. - When returned on a response, this is the effective execution mode. + - `action: object { commands, max_output_length, timeout_ms }` - - `"standard"` + The shell commands and limits that describe how to run the tool call. - - `"pro"` + - `commands: array of string` - - `summary: optional "auto" or "concise" or "detailed"` + - `max_output_length: 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`. + Optional maximum number of characters to return from each command. - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + - `timeout_ms: number` - - `"auto"` + Optional timeout in milliseconds for the commands. - - `"concise"` + - `call_id: string` - - `"detailed"` + The unique ID of the shell tool call generated by the model. - - `safety_identifier: optional string` + - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` - 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](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + Represents the use of a local environment to perform shell actions. - - `service_tier: optional "auto" or "default" or "flex" or 2 more` + - `BetaResponseLocalEnvironment object { type }` - Specifies the processing type used for serving the request. + Represents the use of a local environment to perform shell actions. - - 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](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. + - `type: "local"` - 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 environment type. Always `local`. - - `"auto"` + - `"local"` - - `"default"` + - `BetaResponseContainerReference object { container_id, type }` - - `"flex"` + Represents a container created with /v1/containers. - - `"scale"` + - `container_id: string` - - `"priority"` + - `type: "container_reference"` - - `status: optional BetaResponseStatus` + The environment type. Always `container_reference`. - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + - `"container_reference"` - - `"completed"` + - `status: "in_progress" or "completed" or "incomplete"` - - `"failed"` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - `"in_progress"` - - `"cancelled"` - - - `"queued"` + - `"completed"` - `"incomplete"` - - `text: optional BetaResponseTextConfig` + - `type: "shell_call"` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + The type of the item. Always `shell_call`. - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `"shell_call"` - - `format: optional BetaResponseFormatTextConfig` + - `agent: optional object { agent_name }` - An object specifying the format that the model must output. + The agent that produced this item. - Configuring `{ "type": "json_schema" }` enables Structured Outputs, - which ensures the model will match your supplied JSON schema. Learn more in the - [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `agent_name: string` - The default format is `{ "type": "text" }` with no additional options. + The canonical name of the agent that produced this item. - **Not recommended for gpt-4o and newer models:** + - `caller: optional object { type } or object { caller_id, type }` - 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 execution context that produced this tool call. - - `Text 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` - - `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](https://platform.openai.com/docs/guides/structured-outputs). + - `type: "program"` - - `name: string` + - `"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. + - `created_by: optional string` - - `schema: map[unknown]` + The ID of the entity that created this 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/). + - `ShellCallOutput object { id, call_id, max_output_length, 6 more }` - - `type: "json_schema"` + The output of a shell tool call that was emitted. - The type of response format being defined. Always `json_schema`. + - `id: string` - - `"json_schema"` + The unique ID of the shell call output. Populated when this item is returned via API. - - `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 shell tool call generated by the model. - - `strict: optional boolean` + - `max_output_length: 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](https://platform.openai.com/docs/guides/structured-outputs). + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - `JSONObject object { type }` + - `output: array of object { outcome, stderr, stdout, created_by }` - 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 array of shell call output contents - - `type: "json_object"` + - `outcome: object { type } or object { exit_code, type }` - The type of response format being defined. Always `json_object`. + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - - `"json_object"` + - `Timeout object { type }` - - `verbosity: optional "low" or "medium" or "high"` + Indicates that the shell call exceeded its configured time limit. - 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`. + - `type: "timeout"` - - `"low"` + The outcome type. Always `timeout`. - - `"medium"` + - `"timeout"` - - `"high"` + - `Exit object { exit_code, type }` - - `top_logprobs: optional number` + Indicates that the shell commands finished and returned an exit code. - 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. + - `exit_code: number` - - `truncation: optional "auto" or "disabled"` + Exit code from the shell process. - The truncation strategy to use for the model response. + - `type: "exit"` - - `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 outcome type. Always `exit`. - - `"auto"` + - `"exit"` - - `"disabled"` + - `stderr: string` - - `usage: optional BetaResponseUsage` + The standard error output that was captured. - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + - `stdout: string` - - `input_tokens: number` + The standard output that was captured. - The number of input tokens. + - `created_by: optional string` - - `input_tokens_details: object { cache_write_tokens, cached_tokens }` + The identifier of the actor that created the item. - A detailed breakdown of the input tokens. + - `status: "in_progress" or "completed" or "incomplete"` - - `cache_write_tokens: number` + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - The number of input tokens that were written to the cache. + - `"in_progress"` - - `cached_tokens: number` + - `"completed"` - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + - `"incomplete"` - - `output_tokens: number` + - `type: "shell_call_output"` - The number of output tokens. + The type of the shell call output. Always `shell_call_output`. - - `output_tokens_details: object { reasoning_tokens }` + - `"shell_call_output"` - A detailed breakdown of the output tokens. + - `agent: optional object { agent_name }` - - `reasoning_tokens: number` + The agent that produced this item. - The number of reasoning tokens. + - `agent_name: string` - - `total_tokens: number` + The canonical name of the agent that produced this item. - The total number of tokens used. + - `caller: optional object { type } or object { caller_id, type }` - - `user: optional string` + The execution context that produced this 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](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `Direct object { type }` -### Beta Response Audio Delta Event + - `type: "direct"` -- `BetaResponseAudioDeltaEvent object { delta, sequence_number, type, agent }` + - `"direct"` - Emitted when there is a partial audio response. + - `Program object { caller_id, type }` - - `delta: string` + - `caller_id: string` - A chunk of Base64 encoded response audio bytes. + The call ID of the program item that produced this tool call. - - `sequence_number: number` + - `type: "program"` - A sequence number for this chunk of the stream response. + - `"program"` - - `type: "response.audio.delta"` + - `created_by: optional string` - The type of the event. Always `response.audio.delta`. + The identifier of the actor that created the item. - - `"response.audio.delta"` + - `ApplyPatchCall object { id, call_id, operation, 5 more }` - - `agent: optional object { agent_name }` + A tool call that applies file diffs by creating, deleting, or updating files. - The agent that owns this multi-agent streaming event. + - `id: string` - - `agent_name: string` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - The canonical name of the agent that produced this item. + - `call_id: string` -### Beta Response Audio Done Event + The unique ID of the apply patch tool call generated by the model. -- `BetaResponseAudioDoneEvent object { sequence_number, type, agent }` + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - Emitted when the audio response is complete. + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `sequence_number: number` + - `CreateFile object { diff, path, type }` - The sequence number of the delta. + Instruction describing how to create a file via the apply_patch tool. - - `type: "response.audio.done"` + - `diff: string` - The type of the event. Always `response.audio.done`. + Diff to apply. - - `"response.audio.done"` + - `path: string` - - `agent: optional object { agent_name }` + Path of the file to create. - The agent that owns this multi-agent streaming event. + - `type: "create_file"` - - `agent_name: string` + Create a new file with the provided diff. - The canonical name of the agent that produced this item. + - `"create_file"` -### Beta Response Audio Transcript Delta Event + - `DeleteFile object { path, type }` -- `BetaResponseAudioTranscriptDeltaEvent object { delta, sequence_number, type, agent }` + Instruction describing how to delete a file via the apply_patch tool. - Emitted when there is a partial transcript of audio. + - `path: string` - - `delta: string` + Path of the file to delete. - The partial transcript of the audio response. + - `type: "delete_file"` - - `sequence_number: number` + Delete the specified file. - The sequence number of this event. + - `"delete_file"` - - `type: "response.audio.transcript.delta"` + - `UpdateFile object { diff, path, type }` - The type of the event. Always `response.audio.transcript.delta`. + Instruction describing how to update a file via the apply_patch tool. - - `"response.audio.transcript.delta"` + - `diff: string` - - `agent: optional object { agent_name }` + Diff to apply. - The agent that owns this multi-agent streaming event. + - `path: string` - - `agent_name: string` + Path of the file to update. - The canonical name of the agent that produced this item. + - `type: "update_file"` -### Beta Response Audio Transcript Done Event + Update an existing file with the provided diff. -- `BetaResponseAudioTranscriptDoneEvent object { sequence_number, type, agent }` + - `"update_file"` - Emitted when the full audio transcript is completed. + - `status: "in_progress" or "completed"` - - `sequence_number: number` + The status of the apply patch tool call. One of `in_progress` or `completed`. - The sequence number of this event. + - `"in_progress"` - - `type: "response.audio.transcript.done"` + - `"completed"` - The type of the event. Always `response.audio.transcript.done`. + - `type: "apply_patch_call"` - - `"response.audio.transcript.done"` + The type of the item. Always `apply_patch_call`. + + - `"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 Code Interpreter Call Code Delta Event - -- `BetaResponseCodeInterpreterCallCodeDeltaEvent object { delta, item_id, output_index, 3 more }` - - Emitted when a partial code snippet is streamed by the code interpreter. - - - `delta: string` - - The partial code snippet being streamed by the code interpreter. - - - `item_id: string` - - The unique identifier of the code interpreter tool call item. - - - `output_index: number` + - `caller: optional object { type } or object { caller_id, type }` - The index of the output item in the response for which the code is being streamed. + The execution context that produced this tool call. - - `sequence_number: number` + - `Direct object { type }` - The sequence number of this event, used to order streaming events. + - `type: "direct"` - - `type: "response.code_interpreter_call_code.delta"` + - `"direct"` - The type of the event. Always `response.code_interpreter_call_code.delta`. + - `Program object { caller_id, type }` - - `"response.code_interpreter_call_code.delta"` + - `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` + - `"program"` - The canonical name of the agent that produced this item. + - `created_by: optional string` -### Beta Response Code Interpreter Call Code Done Event + The ID of the entity that created this tool call. -- `BetaResponseCodeInterpreterCallCodeDoneEvent object { code, item_id, output_index, 3 more }` + - `ApplyPatchCallOutput object { id, call_id, status, 5 more }` - Emitted when the code snippet is finalized by the code interpreter. + The output emitted by an apply patch tool call. - - `code: string` + - `id: string` - The final code snippet output by the code interpreter. + The unique ID of the apply patch tool 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 apply patch tool call generated by the model. - - `output_index: number` + - `status: "completed" or "failed"` - The index of the output item in the response for which the code is finalized. + The status of the apply patch tool call output. One of `completed` or `failed`. - - `sequence_number: number` + - `"completed"` - The sequence number of this event, used to order streaming events. + - `"failed"` - - `type: "response.code_interpreter_call_code.done"` + - `type: "apply_patch_call_output"` - The type of the event. Always `response.code_interpreter_call_code.done`. + The type of the item. Always `apply_patch_call_output`. - - `"response.code_interpreter_call_code.done"` + - `"apply_patch_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. -### Beta Response Code Interpreter Call Completed Event - -- `BetaResponseCodeInterpreterCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` + - `caller: optional object { type } or object { caller_id, type }` - Emitted when the code interpreter call is completed. + The execution context that produced this tool call. - - `item_id: string` + - `Direct object { type }` - The unique identifier of the code interpreter tool call item. + - `type: "direct"` - - `output_index: number` + - `"direct"` - The index of the output item in the response for which the code interpreter call is completed. + - `Program object { caller_id, type }` - - `sequence_number: number` + - `caller_id: string` - The sequence number of this event, used to order streaming events. + The call ID of the program item that produced this tool call. - - `type: "response.code_interpreter_call.completed"` + - `type: "program"` - The type of the event. Always `response.code_interpreter_call.completed`. + - `"program"` - - `"response.code_interpreter_call.completed"` + - `created_by: optional string` - - `agent: optional object { agent_name }` + The ID of the entity that created this tool call output. - The agent that owns this multi-agent streaming event. + - `output: optional string` - - `agent_name: string` + Optional textual output returned by the apply patch tool. - The canonical name of the agent that produced this item. + - `McpCall object { id, arguments, name, 7 more }` -### Beta Response Code Interpreter Call In Progress Event + An invocation of a tool on an MCP server. -- `BetaResponseCodeInterpreterCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` + - `id: string` - Emitted when a code interpreter call is in progress. + The unique ID of the tool call. - - `item_id: string` + - `arguments: string` - The unique identifier of the code interpreter tool call item. + A JSON string of the arguments passed to the tool. - - `output_index: number` + - `name: string` - The index of the output item in the response for which the code interpreter call is in progress. + The name of the tool that was run. - - `sequence_number: number` + - `server_label: string` - The sequence number of this event, used to order streaming events. + The label of the MCP server running the tool. - - `type: "response.code_interpreter_call.in_progress"` + - `type: "mcp_call"` - The type of the event. Always `response.code_interpreter_call.in_progress`. + The type of the item. Always `mcp_call`. - - `"response.code_interpreter_call.in_progress"` + - `"mcp_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 Code Interpreter Call Interpreting Event - -- `BetaResponseCodeInterpreterCallInterpretingEvent object { item_id, output_index, sequence_number, 2 more }` - - Emitted when the code interpreter is actively interpreting the code snippet. + - `approval_request_id: optional string` - - `item_id: string` + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - The unique identifier of the code interpreter tool call item. + - `error: optional string` - - `output_index: number` + The error from the tool call, if any. - The index of the output item in the response for which the code interpreter is interpreting code. + - `output: optional string` - - `sequence_number: number` + The output from the tool call. - The sequence number of this event, used to order streaming events. + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - - `type: "response.code_interpreter_call.interpreting"` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - The type of the event. Always `response.code_interpreter_call.interpreting`. + - `"in_progress"` - - `"response.code_interpreter_call.interpreting"` + - `"completed"` - - `agent: optional object { agent_name }` + - `"incomplete"` - The agent that owns this multi-agent streaming event. + - `"calling"` - - `agent_name: string` + - `"failed"` - The canonical name of the agent that produced this item. + - `McpListTools object { id, server_label, tools, 3 more }` -### Beta Response Completed Event + A list of tools available on an MCP server. -- `BetaResponseCompletedEvent object { response, sequence_number, type, agent }` + - `id: string` - Emitted when the model response is complete. + The unique ID of the list. - - `response: BetaResponse` + - `server_label: string` - Properties of the completed response. + The label of the MCP server. - - `id: string` + - `tools: array of object { input_schema, name, annotations, description }` - Unique identifier for this Response. + The tools available on the server. - - `created_at: number` + - `input_schema: unknown` - Unix timestamp (in seconds) of when this Response was created. + The JSON schema describing the tool's input. - - `error: BetaResponseError` + - `name: string` - An error object returned when the model fails to generate a Response. + The name of the tool. - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 16 more` + - `annotations: optional unknown` - The error code for the response. + Additional annotations about the tool. - - `"server_error"` + - `description: optional string` - - `"rate_limit_exceeded"` + The description of the tool. - - `"invalid_prompt"` + - `type: "mcp_list_tools"` - - `"bio_policy"` + The type of the item. Always `mcp_list_tools`. - - `"vector_store_timeout"` + - `"mcp_list_tools"` - - `"invalid_image"` + - `agent: optional object { agent_name }` - - `"invalid_image_format"` + The agent that produced this item. - - `"invalid_base64_image"` + - `agent_name: string` - - `"invalid_image_url"` + The canonical name of the agent that produced this item. - - `"image_too_large"` + - `error: optional string` - - `"image_too_small"` + Error message if the server could not list tools. - - `"image_parse_error"` + - `McpApprovalRequest object { id, arguments, name, 3 more }` - - `"image_content_policy_violation"` + A request for human approval of a tool invocation. - - `"invalid_image_mode"` + - `id: string` - - `"image_file_too_large"` + The unique ID of the approval request. - - `"unsupported_image_media_type"` + - `arguments: string` - - `"empty_image_file"` + A JSON string of arguments for the tool. - - `"failed_to_download_image"` + - `name: string` - - `"image_file_not_found"` + The name of the tool to run. - - `message: string` + - `server_label: string` - A human-readable description of the error. + The label of the MCP server making the request. - - `incomplete_details: object { reason }` + - `type: "mcp_approval_request"` - Details about why the response is incomplete. + The type of the item. Always `mcp_approval_request`. - - `reason: optional "max_output_tokens" or "content_filter"` + - `"mcp_approval_request"` - The reason why the response is incomplete. + - `agent: optional object { agent_name }` - - `"max_output_tokens"` + The agent that produced this item. - - `"content_filter"` + - `agent_name: string` - - `instructions: string or 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 system (or developer) message inserted into the model's context. + - `McpApprovalResponse object { id, approval_request_id, approve, 3 more }` - When using along with `previous_response_id`, the instructions from a previous - response will not be carried over to the next response. This makes it simple - to swap out system (or developer) messages in new responses. + A response to an MCP approval request. - - `string` + - `id: string` - A text input to the model, equivalent to a text input with the - `developer` role. + The unique ID of the approval response - - `InputItemList = array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + - `approval_request_id: string` - A list of one or many input items to the model, containing - different content types. + The ID of the approval request being answered. - - `BetaEasyInputMessage object { content, role, phase, type }` + - `approve: 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. + Whether the request was approved. - - `content: string or BetaResponseInputMessageContentList` + - `type: "mcp_approval_response"` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + The type of the item. Always `mcp_approval_response`. - - `TextInput = string` + - `"mcp_approval_response"` - A text input to the model. + - `agent: optional object { agent_name }` - - `BetaResponseInputMessageContentList = array of BetaResponseInputContent` + The agent that produced this item. - A list of one or many input items to the model, containing different content - types. + - `agent_name: string` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + The canonical name of the agent that produced this item. - A text input to the model. + - `reason: optional string` - - `text: string` + Optional reason for the decision. - The text input to the model. + - `CustomToolCall object { call_id, input, name, 5 more }` - - `type: "input_text"` + A call to a custom tool created by the model. - The type of the input item. Always `input_text`. + - `call_id: string` - - `"input_text"` + An identifier used to map this custom tool call to a tool call output. - - `prompt_cache_breakpoint: optional object { mode }` + - `input: 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 input for the custom tool call generated by the model. - - `mode: "explicit"` + - `name: string` - The breakpoint mode. Always `explicit`. + The name of the custom tool being called. - - `"explicit"` + - `type: "custom_tool_call"` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + The type of the custom tool call. Always `custom_tool_call`. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `"custom_tool_call"` - - `detail: "low" or "high" or "auto" or "original"` + - `id: optional string` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The unique ID of the custom tool call in the OpenAI platform. - - `"low"` + - `agent: optional object { agent_name }` - - `"high"` + The agent that produced this item. - - `"auto"` + - `agent_name: string` - - `"original"` + The canonical name of the agent that produced this item. - - `type: "input_image"` + - `caller: optional object { type } or object { caller_id, type }` - The type of the input item. Always `input_image`. + The execution context that produced this tool call. - - `"input_image"` + - `Direct object { type }` - - `file_id: optional string` + - `type: "direct"` - The ID of the file to be sent to the model. + - `"direct"` - - `image_url: optional string` + - `Program object { caller_id, type }` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `caller_id: string` - - `prompt_cache_breakpoint: optional object { mode }` + The call ID of the program item 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. + - `type: "program"` - - `mode: "explicit"` + - `"program"` - The breakpoint mode. Always `explicit`. + - `namespace: optional string` - - `"explicit"` + The namespace of the custom tool being called. - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `CustomToolCallOutput object { id, call_id, output, 5 more }` - A file input to the model. + - `id: string` - - `type: "input_file"` + The unique ID of the custom tool call output item. - The type of the input item. Always `input_file`. + - `call_id: string` - - `"input_file"` + The call ID, used to map this custom tool call output to a custom tool call. - - `detail: optional "auto" or "low" or "high"` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - 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 output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `"auto"` + - `StringOutput = string` - - `"low"` + A string of the output of the custom tool call. - - `"high"` + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `file_data: optional string` + Text, image, or file output of the custom tool call. - The content of the file to be sent to the model. + - `BetaResponseInputText 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. + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `file_url: optional string` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - The URL of the file to be sent to the model. + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `filename: optional string` + A file input to the model. - The name of the file to be sent to the model. + - `status: "in_progress" or "completed" or "incomplete"` - - `prompt_cache_breakpoint: optional object { mode }` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `"in_progress"` - - `mode: "explicit"` + - `"completed"` - The breakpoint mode. Always `explicit`. + - `"incomplete"` - - `"explicit"` + - `type: "custom_tool_call_output"` - - `role: "user" or "assistant" or "system" or "developer"` + The type of the custom tool call output. Always `custom_tool_call_output`. - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + - `"custom_tool_call_output"` - - `"user"` + - `agent: optional object { agent_name }` - - `"assistant"` + The agent that produced this item. - - `"system"` + - `agent_name: string` - - `"developer"` + The canonical name of the agent that produced this item. - - `phase: optional "commentary" or "final_answer"` + - `caller: optional object { type } or object { caller_id, 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. + The execution context that produced this tool call. - - `"commentary"` + - `Direct object { type }` - - `"final_answer"` + - `type: "direct"` - - `type: optional "message"` + The caller type. Always `direct`. - The type of the message input. Always `message`. + - `"direct"` - - `"message"` + - `Program object { caller_id, type }` - - `Message object { content, role, agent, 2 more }` + - `caller_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. + The call ID of the program item that produced this tool call. - - `content: BetaResponseInputMessageContentList` + - `type: "program"` - A list of one or many input items to the model, containing different content - types. + The caller type. Always `program`. - - `role: "user" or "system" or "developer"` + - `"program"` - The role of the message input. One of `user`, `system`, or `developer`. + - `created_by: optional string` - - `"user"` + The identifier of the actor that created the item. - - `"system"` + - `parallel_tool_calls: boolean` - - `"developer"` + Whether to allow the model to run tool calls in parallel. - - `agent: optional object { agent_name }` + - `temperature: number` - The agent that produced this item. + 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. - - `agent_name: string` + - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` - The canonical name of the agent that produced this item. + 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. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `BetaToolChoiceOptions = "none" or "auto" or "required"` - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Controls which (if any) tool is called by the model. - - `"in_progress"` + `none` means the model will not call any tool and instead generates a message. - - `"completed"` + `auto` means the model can pick between generating a message or calling one or + more tools. - - `"incomplete"` + `required` means the model must call one or more tools. - - `type: optional "message"` + - `"none"` - The type of the message input. Always set to `message`. + - `"auto"` - - `"message"` + - `"required"` - - `BetaResponseOutputMessage object { id, content, role, 4 more }` + - `BetaToolChoiceAllowed object { mode, tools, type }` - An output message from the model. + Constrains the tools available to the model to a pre-defined set. - - `id: string` + - `mode: "auto" or "required"` - The unique ID of the output message. + Constrains the tools available to the model to a pre-defined set. - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + `auto` allows the model to pick from among the allowed tools and generate a + message. - The content of the output message. + `required` requires the model to call one or more of the allowed tools. - - `BetaResponseOutputText object { annotations, text, type, logprobs }` + - `"auto"` - A text output from the model. + - `"required"` - - `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 }` + - `tools: array of map[unknown]` - The annotations of the text output. + A list of tool definitions that the model should be allowed to call. - - `FileCitation object { file_id, filename, index, type }` + For the Responses API, the list of tool definitions might look like: - A citation to a file. + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - - `file_id: string` + - `type: "allowed_tools"` - The ID of the file. + Allowed tool configuration type. Always `allowed_tools`. - - `filename: string` + - `"allowed_tools"` - The filename of the file cited. + - `BetaToolChoiceTypes object { type }` - - `index: number` + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](/docs/guides/tools). - The index of the file in the list of files. + - `type: "file_search" or "web_search_preview" or "computer" or 5 more` - - `type: "file_citation"` + The type of hosted tool the model should to use. Learn more about + [built-in tools](/docs/guides/tools). - The type of the file citation. Always `file_citation`. + Allowed values are: - - `"file_citation"` + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - - `URLCitation object { end_index, start_index, title, 2 more }` + - `"file_search"` - A citation for a web resource used to generate a model response. + - `"web_search_preview"` - - `end_index: number` + - `"computer"` - The index of the last character of the URL citation in the message. + - `"computer_use_preview"` - - `start_index: number` + - `"computer_use"` - The index of the first character of the URL citation in the message. + - `"web_search_preview_2025_03_11"` - - `title: string` + - `"image_generation"` - The title of the web resource. + - `"code_interpreter"` - - `type: "url_citation"` + - `BetaToolChoiceFunction object { name, type }` - The type of the URL citation. Always `url_citation`. + Use this option to force the model to call a specific function. - - `"url_citation"` + - `name: string` - - `url: string` + The name of the function to call. - The URL of the web resource. + - `type: "function"` - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + For function calling, the type is always `function`. - A citation for a container file used to generate a model response. + - `"function"` - - `container_id: string` + - `BetaToolChoiceMcp object { server_label, type, name }` - The ID of the container file. + Use this option to force the model to call a specific tool on a remote MCP server. - - `end_index: number` + - `server_label: string` - The index of the last character of the container file citation in the message. + The label of the MCP server to use. - - `file_id: string` + - `type: "mcp"` - The ID of the file. + For MCP tools, the type is always `mcp`. - - `filename: string` + - `"mcp"` - The filename of the container file cited. + - `name: optional string` - - `start_index: number` + The name of the tool to call on the server. - The index of the first character of the container file citation in the message. + - `BetaToolChoiceCustom object { name, type }` - - `type: "container_file_citation"` + Use this option to force the model to call a specific custom tool. - The type of the container file citation. Always `container_file_citation`. + - `name: string` - - `"container_file_citation"` + The name of the custom tool to call. - - `FilePath object { file_id, index, type }` + - `type: "custom"` - A path to a file. + For custom tool calling, the type is always `custom`. - - `file_id: string` + - `"custom"` - The ID of the file. + - `BetaSpecificProgrammaticToolCallingParam object { type }` - - `index: number` + - `type: "programmatic_tool_calling"` - The index of the file in the list of files. + The tool to call. Always `programmatic_tool_calling`. - - `type: "file_path"` + - `"programmatic_tool_calling"` - The type of the file path. Always `file_path`. + - `BetaToolChoiceApplyPatch object { type }` - - `"file_path"` + Forces the model to call the apply_patch tool when executing a tool call. - - `text: string` + - `type: "apply_patch"` - The text output from the model. + The tool to call. Always `apply_patch`. - - `type: "output_text"` + - `"apply_patch"` - The type of the output text. Always `output_text`. + - `BetaToolChoiceShell object { type }` - - `"output_text"` + Forces the model to call the shell tool when a tool call is required. - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + - `type: "shell"` - - `token: string` + The tool to call. Always `shell`. - - `bytes: array of number` + - `"shell"` - - `logprob: 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` - - `top_logprobs: array of object { token, bytes, logprob }` + 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. - - `token: string` + We support the following categories of tools: - - `bytes: array of 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. - - `logprob: number` + - `Function object { name, parameters, strict, 5 more }` - - `BetaResponseOutputRefusal object { refusal, 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). - A refusal from the model. + - `name: string` - - `refusal: string` + The name of the function to call. - The refusal explanation from the model. + - `parameters: map[unknown]` - - `type: "refusal"` + A JSON schema object describing the parameters of the function. - The type of the refusal. Always `refusal`. + - `strict: boolean` - - `"refusal"` + Whether strict parameter validation is enforced for this function tool. - - `role: "assistant"` + - `type: "function"` - The role of the output message. Always `assistant`. + The type of the function tool. Always `function`. - - `"assistant"` + - `"function"` - - `status: "in_progress" or "completed" or "incomplete"` + - `allowed_callers: optional array of "direct" or "programmatic"` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + The tool invocation context(s). - - `"in_progress"` + - `"direct"` - - `"completed"` + - `"programmatic"` - - `"incomplete"` + - `defer_loading: optional boolean` - - `type: "message"` + Whether this function is deferred and loaded via tool search. - The type of the output message. Always `message`. + - `description: optional string` - - `"message"` + 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). - - `phase: optional "commentary" or "final_answer"` + - `type: "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. + The type of the file search tool. Always `file_search`. - - `"commentary"` + - `"file_search"` - - `"final_answer"` + - `vector_store_ids: array of string` - - `FileSearchCall object { id, queries, status, 3 more }` + The IDs of the vector stores to search. - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `filters: optional object { key, type, value } or object { filters, type }` - - `id: string` + A filter to apply. - The unique ID of the file search tool call. + - `ComparisonFilter object { key, type, value }` - - `queries: array of string` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The queries used to search for files. + - `key: string` - - `status: "in_progress" or "searching" or "completed" or 2 more` + The key to compare against the value. - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `type: "eq" or "ne" or "gt" or 5 more` - - `"in_progress"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `"searching"` + - `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"` - - `"failed"` + - `"gt"` - - `type: "file_search_call"` + - `"gte"` - The type of the file search tool call. Always `file_search_call`. + - `"lt"` - - `"file_search_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. - - `results: optional array of object { attributes, file_id, filename, 2 more }` + - `string` - The results of the file search tool call. + - `number` - - `attributes: optional map[string or number or boolean]` + - `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. + - `array of string or number` - `string` - `number` - - `boolean` + - `CompoundFilter object { filters, type }` - - `file_id: optional string` + Combine multiple filters using `and` or `or`. - The unique ID of the file. + - `filters: array of object { key, type, value } or unknown` - - `filename: optional string` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - The name of the file. + - `ComparisonFilter object { key, type, value }` - - `score: optional number` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The relevance score of the file - a value between 0 and 1. + - `key: string` - - `text: optional string` + The key to compare against the value. - The text that was retrieved from the file. + - `type: "eq" or "ne" or "gt" or 5 more` - - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + - `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 unique ID of the computer call. + - `"ne"` - - `call_id: string` + - `"gt"` - An identifier used when responding to the tool call with output. + - `"gte"` - - `pending_safety_checks: array of object { id, code, message }` + - `"lt"` - The pending safety checks for the computer call. + - `"lte"` - - `id: string` + - `"in"` - The ID of the pending safety check. + - `"nin"` - - `code: optional string` + - `value: string or number or boolean or array of string or number` - The type of the pending safety check. + The value to compare against the attribute key; supports string, number, or boolean types. - - `message: optional string` + - `string` - Details about the pending safety check. + - `number` - - `status: "in_progress" or "completed" or "incomplete"` + - `boolean` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `array of string or number` - - `"in_progress"` + - `string` - - `"completed"` + - `number` - - `"incomplete"` + - `unknown` - - `type: "computer_call"` + - `type: "and" or "or"` - The type of the computer call. Always `computer_call`. + Type of operation: `and` or `or`. - - `"computer_call"` + - `"and"` - - `action: optional BetaComputerAction` + - `"or"` - A click action. + - `max_num_results: optional number` - - `Click object { button, type, x, 2 more }` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - A click action. + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `button: "left" or "right" or "wheel" or 2 more` + Ranking options for search. - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `hybrid_search: optional object { embedding_weight, text_weight }` - - `"left"` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `"right"` + - `embedding_weight: number` - - `"wheel"` + The weight of the embedding in the reciprocal ranking fusion. - - `"back"` + - `text_weight: number` - - `"forward"` + The weight of the text in the reciprocal ranking fusion. - - `type: "click"` + - `ranker: optional "auto" or "default-2024-11-15"` - Specifies the event type. For a click action, this property is always `click`. + The ranker to use for the file search. - - `"click"` + - `"auto"` - - `x: number` + - `"default-2024-11-15"` - The x-coordinate where the click occurred. + - `score_threshold: optional number` - - `y: number` + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - The y-coordinate where the click occurred. + - `Computer object { type }` - - `keys: optional array of string` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The keys being held while clicking. + - `type: "computer"` - - `DoubleClick object { keys, type, x, y }` + The type of the computer tool. Always `computer`. - A double click action. + - `"computer"` - - `keys: array of string` + - `ComputerUsePreview object { display_height, display_width, environment, type }` - The keys being held while double-clicking. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `type: "double_click"` + - `display_height: number` - Specifies the event type. For a double click action, this property is always set to `double_click`. + The height of the computer display. - - `"double_click"` + - `display_width: number` - - `x: number` + The width of the computer display. - The x-coordinate where the double click occurred. + - `environment: "windows" or "mac" or "linux" or 2 more` - - `y: number` + The type of computer environment to control. - The y-coordinate where the double click occurred. + - `"windows"` - - `Drag object { path, type, keys }` + - `"mac"` - A drag action. + - `"linux"` - - `path: array of object { x, y }` + - `"ubuntu"` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `"browser"` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `type: "computer_use_preview"` - - `x: number` + The type of the computer use tool. Always `computer_use_preview`. - The x-coordinate. + - `"computer_use_preview"` - - `y: number` + - `WebSearch object { type, filters, search_context_size, user_location }` - The y-coordinate. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - - `type: "drag"` + - `type: "web_search" or "web_search_2025_08_26"` - Specifies the event type. For a drag action, this property is always set to `drag`. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `"drag"` + - `"web_search"` - - `keys: optional array of string` + - `"web_search_2025_08_26"` - The keys being held while dragging the mouse. + - `filters: optional object { allowed_domains }` - - `Keypress object { keys, type }` + Filters for the search. - A collection of keypresses the model would like to perform. + - `allowed_domains: optional array of string` - - `keys: 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 combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `type: "keypress"` + - `search_context_size: optional "low" or "medium" or "high"` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + 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. - - `"keypress"` + - `"low"` - - `Move object { type, x, y, keys }` + - `"medium"` - A mouse move action. + - `"high"` - - `type: "move"` + - `user_location: optional object { city, country, region, 2 more }` - Specifies the event type. For a move action, this property is always set to `move`. + The approximate location of the user. - - `"move"` + - `city: optional string` - - `x: number` + Free text input for the city of the user, e.g. `San Francisco`. - The x-coordinate to move to. + - `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 to move to. + - `region: optional string` - - `keys: optional array of string` + Free text input for the region of the user, e.g. `California`. - The keys being held while moving the mouse. + - `timezone: optional string` - - `Screenshot object { type }` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - A screenshot action. + - `type: optional "approximate"` - - `type: "screenshot"` + The type of location approximation. Always `approximate`. - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `"approximate"` - - `"screenshot"` + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `Scroll object { scroll_x, scroll_y, type, 3 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 scroll action. + - `server_label: string` - - `scroll_x: number` + A label for this MCP server, used to identify it in tool calls. - The horizontal scroll distance. + - `type: "mcp"` - - `scroll_y: number` + The type of the MCP tool. Always `mcp`. - The vertical scroll distance. + - `"mcp"` - - `type: "scroll"` + - `allowed_callers: optional array of "direct" or "programmatic"` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + The tool invocation context(s). - - `"scroll"` + - `"direct"` - - `x: number` + - `"programmatic"` - The x-coordinate where the scroll occurred. + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `y: number` + List of allowed tool names or a filter object. - The y-coordinate where the scroll occurred. + - `McpAllowedTools = array of string` - - `keys: optional array of string` + A string array of allowed tool names - The keys being held while scrolling. + - `McpToolFilter object { read_only, tool_names }` - - `Type object { text, type }` + A filter object to specify which tools are allowed. - An action to type in text. + - `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 to type. + - `tool_names: optional array of string` - - `type: "type"` + List of allowed tool names. - Specifies the event type. For a type action, this property is always set to `type`. + - `authorization: optional string` - - `"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. - - `Wait object { type }` + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - A wait action. + 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: "wait"` + Currently supported `connector_id` values are: - Specifies the event type. For a wait action, this property is always set to `wait`. + - 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` - - `"wait"` + - `"connector_dropbox"` - - `actions: optional BetaComputerActionList` + - `"connector_gmail"` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `"connector_googlecalendar"` - - `Click object { button, type, x, 2 more }` + - `"connector_googledrive"` - A click action. + - `"connector_microsoftteams"` - - `DoubleClick object { keys, type, x, y }` + - `"connector_outlookcalendar"` - A double click action. + - `"connector_outlookemail"` - - `Drag object { path, type, keys }` + - `"connector_sharepoint"` - A drag action. + - `defer_loading: optional boolean` - - `Keypress object { keys, type }` + Whether this MCP tool is deferred and discovered via tool search. - A collection of keypresses the model would like to perform. + - `headers: optional map[string]` - - `Move object { type, x, y, keys }` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - A mouse move action. + - `require_approval: optional object { always, never } or "always" or "never"` - - `Screenshot object { type }` + Specify which of the MCP server's tools require approval. - A screenshot action. + - `McpToolApprovalFilter object { always, never }` - - `Scroll object { scroll_x, scroll_y, type, 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. - A scroll action. + - `always: optional object { read_only, tool_names }` - - `Type object { text, type }` + A filter object to specify which tools are allowed. - An action to type in text. + - `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` - - `agent: optional object { agent_name }` + List of allowed tool names. - The agent that produced this item. + - `never: 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` - - `ComputerCallOutput object { call_id, output, type, 4 more }` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - The output of a computer tool call. + - `tool_names: optional array of string` - - `call_id: string` + List of allowed tool names. - The ID of the computer tool call that produced the output. + - `McpToolApprovalSetting = "always" or "never"` - - `output: BetaResponseComputerToolCallOutputScreenshot` + 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 computer screenshot image used with the computer use tool. + - `"always"` - - `type: "computer_screenshot"` + - `"never"` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `server_description: optional string` - - `"computer_screenshot"` + Optional description of the MCP server, used to provide more context. - - `file_id: optional string` + - `server_url: optional string` - The identifier of an uploaded file that contains the screenshot. + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `image_url: optional string` + - `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. - The URL of the screenshot image. + - `CodeInterpreter object { container, type, allowed_callers }` - - `type: "computer_call_output"` + A tool that runs Python code to help generate a response to a prompt. - The type of the computer tool call output. Always `computer_call_output`. + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `"computer_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. - - `id: optional string` + - `string` - The ID of the computer tool call output. + The container ID. - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - The safety checks reported by the API that have been acknowledged by the developer. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `id: string` + - `type: "auto"` - The ID of the pending safety check. + Always `auto`. - - `code: optional string` + - `"auto"` - The type of the pending safety check. + - `file_ids: optional array of string` - - `message: optional string` + An optional list of uploaded files to make available to your code. - Details about the pending safety check. + - `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"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"64g"` - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `"in_progress"` + Network access policy for the container. - - `"completed"` + - `BetaContainerNetworkPolicyDisabled object { type }` - - `"incomplete"` + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `WebSearchCall object { id, action, status, 2 more }` + - `type: "code_interpreter"` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + The type of the code interpreter tool. Always `code_interpreter`. - - `id: string` + - `"code_interpreter"` - 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. + - `ProgrammaticToolCalling object { type }` - - `type: "search"` + - `type: "programmatic_tool_calling"` - The action type. + The type of the tool. Always `programmatic_tool_calling`. - - `"search"` + - `"programmatic_tool_calling"` - - `queries: optional array of string` + - `ImageGeneration object { type, action, background, 9 more }` - The search queries. + A tool that generates images using the GPT image models. - - `query: optional string` + - `type: "image_generation"` - The search query. + The type of the image generation tool. Always `image_generation`. - - `sources: optional array of object { type, url }` + - `"image_generation"` - The sources used in the search. + - `action: optional "generate" or "edit" or "auto"` - - `type: "url"` + Whether to generate a new image or edit an existing image. Default: `auto`. - The type of source. Always `url`. + - `"generate"` - - `"url"` + - `"edit"` - - `url: string` + - `"auto"` - The URL of the source. + - `background: optional "transparent" or "opaque" or "auto"` - - `OpenPage object { type, url }` + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - Action type "open_page" - Opens a specific URL from search results. + - `"transparent"` - - `type: "open_page"` + - `"opaque"` - The action type. + - `"auto"` - - `"open_page"` + - `input_fidelity: optional "high" or "low"` - - `url: 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 URL opened by the model. + - `"high"` - - `FindInPage object { pattern, type, url }` + - `"low"` - Action type "find_in_page": Searches for a pattern within a loaded page. + - `input_image_mask: optional object { file_id, image_url }` - - `pattern: string` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - The pattern or text to search for within the page. + - `file_id: optional string` - - `type: "find_in_page"` + File ID for the mask image. - The action type. + - `image_url: optional string` - - `"find_in_page"` + Base64-encoded mask image. - - `url: string` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - The URL of the page searched for the pattern. + The image generation model to use. Default: `gpt-image-1`. - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `string` - The status of the web search tool call. + - `"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`. - - `"searching"` + - `"gpt-image-1"` - - `"completed"` + - `"gpt-image-1-mini"` - - `"failed"` + - `"gpt-image-1.5"` - - `type: "web_search_call"` + - `moderation: optional "auto" or "low"` - The type of the web search tool call. Always `web_search_call`. + Moderation level for the generated image. Default: `auto`. - - `"web_search_call"` + - `"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"` - - `FunctionCall object { arguments, call_id, name, 6 more }` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `"png"` - - `arguments: string` + - `"webp"` - A JSON string of the arguments to pass to the function. + - `"jpeg"` - - `call_id: string` + - `partial_images: optional number` - The unique ID of the function tool call generated by the model. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `name: string` + - `quality: optional "low" or "medium" or "high" or "auto"` - The name of the function to run. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `type: "function_call"` + - `"low"` - The type of the function tool call. Always `function_call`. + - `"medium"` - - `"function_call"` + - `"high"` - - `id: optional string` + - `"auto"` - The unique ID of the function tool call. + - `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 }` - - `namespace: optional string` + A tool that allows the model to execute shell commands. - The namespace of the function to run. + - `type: "shell"` - - `status: optional "in_progress" or "completed" or "incomplete"` + The type of the shell tool. Always `shell`. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"shell"` - - `"in_progress"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"completed"` + The tool invocation context(s). - - `"incomplete"` + - `"direct"` - - `FunctionCallOutput object { call_id, output, type, 4 more }` + - `"programmatic"` - The output of a function tool call. + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - `call_id: string` + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - The unique ID of the function tool call generated by the model. + - `BetaLocalEnvironment object { type, skills }` - - `output: string or BetaResponseFunctionCallOutputItemList` + - `BetaContainerReference object { container_id, type }` - Text, image, or file output of the function tool call. + - `Custom object { name, type, allowed_callers, 3 more }` - - `string` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - A JSON string of the output of the function tool call. + - `name: string` - - `BetaResponseFunctionCallOutputItemList = array of BetaResponseFunctionCallOutputItem` + The name of the custom tool, used to identify it in tool calls. - An array of content outputs (text, image, file) for the function tool call. + - `type: "custom"` - - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` + The type of the custom tool. Always `custom`. - A text input to the model. + - `"custom"` - - `text: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The text input to the model. + The tool invocation context(s). - - `type: "input_text"` + - `"direct"` - The type of the input item. Always `input_text`. + - `"programmatic"` - - `"input_text"` + - `defer_loading: optional boolean` - - `prompt_cache_breakpoint: optional object { mode }` + Whether this tool should be deferred and discovered via tool search. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `description: optional string` - - `mode: "explicit"` + Optional description of the custom tool, used to provide more context. - The breakpoint mode. Always `explicit`. + - `format: optional object { type } or object { definition, syntax, type }` - - `"explicit"` + The input format for the custom tool. Default is unconstrained text. - - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` + - `Text object { type }` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + Unconstrained free-form text. - - `type: "input_image"` + - `type: "text"` - The type of the input item. Always `input_image`. + Unconstrained text format. Always `text`. - - `"input_image"` + - `"text"` - - `detail: optional "low" or "high" or "auto" or "original"` + - `Grammar object { definition, syntax, type }` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + A grammar defined by the user. - - `"low"` + - `definition: string` - - `"high"` + The grammar definition. - - `"auto"` + - `syntax: "lark" or "regex"` - - `"original"` + The syntax of the grammar definition. One of `lark` or `regex`. - - `file_id: optional string` + - `"lark"` - The ID of the file to be sent to the model. + - `"regex"` - - `image_url: optional string` + - `type: "grammar"` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + Grammar format. Always `grammar`. - - `prompt_cache_breakpoint: optional object { mode }` + - `"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. + - `Namespace object { description, name, tools, type }` - - `mode: "explicit"` + Groups function/custom tools under a shared namespace. - The breakpoint mode. Always `explicit`. + - `description: string` - - `"explicit"` + A description of the namespace shown to the model. - - `BetaResponseInputFileContent object { type, detail, file_data, 4 more }` + - `name: string` - A file input to the model. + The namespace name used in tool calls (for example, `crm`). - - `type: "input_file"` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - The type of the input item. Always `input_file`. + The function/custom tools available inside this namespace. - - `"input_file"` + - `Function object { name, type, allowed_callers, 5 more }` - - `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`. + - `type: "function"` - - `"auto"` + - `"function"` - - `"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` + - `defer_loading: optional boolean` - The ID of the file to be sent to the model. + Whether this function should be deferred and discovered via tool search. - - `file_url: optional string` + - `description: optional string` - The URL of the file to be sent to the model. + - `output_schema: optional map[unknown]` - - `filename: 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 name of the file to be sent to the model. + - `parameters: optional unknown` - - `prompt_cache_breakpoint: optional object { mode }` + - `strict: optional boolean` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + Whether 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. - - `mode: "explicit"` + - `Custom object { name, type, allowed_callers, 3 more }` - The breakpoint mode. Always `explicit`. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `"explicit"` + - `name: string` - - `type: "function_call_output"` + The name of the custom tool, used to identify it in tool calls. - The type of the function tool call output. Always `function_call_output`. + - `type: "custom"` - - `"function_call_output"` + The type of the custom tool. Always `custom`. - - `id: optional string` + - `"custom"` - The unique ID of the function tool call output. Populated when this item is returned via API. + - `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 }` - The caller type. Always `direct`. + The input format for the custom tool. Default is unconstrained text. - - `"direct"` + - `Text object { type }` - - `Program object { caller_id, type }` + Unconstrained free-form text. - - `caller_id: string` + - `type: "text"` - The call ID of the program item that produced this tool call. + Unconstrained text format. Always `text`. - - `type: "program"` + - `"text"` - The caller type. Always `program`. + - `Grammar object { definition, syntax, type }` - - `"program"` + A grammar defined by the user. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `definition: string` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + The grammar definition. - - `"in_progress"` + - `syntax: "lark" or "regex"` - - `"completed"` + The syntax of the grammar definition. One of `lark` or `regex`. - - `"incomplete"` + - `"lark"` - - `AgentMessage object { author, content, recipient, 3 more }` + - `"regex"` - A message routed between agents. + - `type: "grammar"` - - `author: string` + Grammar format. Always `grammar`. - The sending agent identity. + - `"grammar"` - - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` + - `type: "namespace"` - Plaintext, image, or encrypted content sent between agents. + The type of the tool. Always `namespace`. - - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` + - `"namespace"` - A text input to the model. + - `ToolSearch object { type, description, execution, parameters }` - - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` + Hosted or BYOT tool search configuration for deferred tools. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `type: "tool_search"` - - `EncryptedContent object { encrypted_content, type }` + The type of the tool. Always `tool_search`. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `"tool_search"` - - `encrypted_content: string` + - `description: optional string` - Opaque encrypted content. + Description shown to the model for a client-executed tool search tool. - - `type: "encrypted_content"` + - `execution: optional "server" or "client"` - The type of the input item. Always `encrypted_content`. + Whether tool search is executed by the server or by the client. - - `"encrypted_content"` + - `"server"` - - `recipient: string` + - `"client"` - The destination agent identity. + - `parameters: optional unknown` - - `type: "agent_message"` + Parameter schema for a client-executed tool search tool. - The item type. Always `agent_message`. + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - - `"agent_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). - - `id: optional string` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - The unique ID of this agent message item. + 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"` - - `MultiAgentCall object { action, arguments, call_id, 3 more }` + - `"image"` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `search_context_size: optional "low" or "medium" or "high"` - The multi-agent action that was executed. + 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. - - `"spawn_agent"` + - `"low"` - - `"interrupt_agent"` + - `"medium"` - - `"list_agents"` + - `"high"` - - `"send_message"` + - `user_location: optional object { type, city, country, 2 more }` - - `"followup_task"` + The user's location. - - `"wait_agent"` + - `type: "approximate"` - - `arguments: string` + The type of location approximation. Always `approximate`. - The action arguments as a JSON string. + - `"approximate"` - - `call_id: string` + - `city: optional string` - The unique ID linking this call to its output. + Free text input for the city of the user, e.g. `San Francisco`. - - `type: "multi_agent_call"` + - `country: optional string` - The item type. Always `multi_agent_call`. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `"multi_agent_call"` + - `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. + - `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"` - - `MultiAgentCallOutput object { action, call_id, output, 3 more }` + The type of the tool. Always `apply_patch`. - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `"apply_patch"` - The multi-agent action that produced this result. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"spawn_agent"` + The tool invocation context(s). - - `"interrupt_agent"` + - `"direct"` - - `"list_agents"` + - `"programmatic"` - - `"send_message"` + - `top_p: number` - - `"followup_task"` + 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. - - `"wait_agent"` + We generally recommend altering this or `temperature` but not both. - - `call_id: string` + - `background: optional boolean` - The unique ID of the multi-agent call. + Whether to run the model response in the background. + [Learn more](/docs/guides/background). - - `output: array of object { text, type, annotations }` + - `completed_at: optional number` - Text output returned by the multi-agent action. + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - - `text: string` + - `conversation: optional object { id }` - The text content. + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - - `type: "output_text"` + - `id: string` - The content type. Always `output_text`. + The unique ID of the conversation that this response was associated with. - - `"output_text"` + - `max_output_tokens: optional number` - - `annotations: optional array of object { file_id, filename, index, type } or array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 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). - Citations associated with the text content. + - `max_tool_calls: optional number` - - `array of object { file_id, filename, index, type }` + 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. - - `file_id: string` + - `moderation: optional object { input, output }` - The ID of the file. + Moderation results for the response input and output, if moderated completions were requested. - - `filename: string` + - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` - The filename of the file cited. + Moderation for the response input. - - `index: number` + - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` - The index of the file in the list of files. + A moderation result produced for the response input or output. - - `type: "file_citation"` + - `categories: map[boolean]` - The citation type. Always `file_citation`. + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `"file_citation"` + - `category_applied_input_types: map[array of "text" or "image"]` - - `array of object { end_index, start_index, title, 2 more }` + Which modalities of input are reflected by the score for each category. - - `end_index: number` + - `"text"` - The index of the last character of the citation in the message. + - `"image"` - - `start_index: number` + - `category_scores: map[number]` - The index of the first character of the citation in the message. + A dictionary of moderation categories to scores. - - `title: string` + - `flagged: boolean` - The title of the cited resource. + A boolean indicating whether the content was flagged by any category. - - `type: "url_citation"` + - `model: string` - The citation type. Always `url_citation`. + The moderation model that produced this result. - - `"url_citation"` + - `type: "moderation_result"` - - `url: string` + The object type, which was always `moderation_result` for successful moderation results. - The URL of the cited resource. + - `"moderation_result"` - - `array of object { container_id, end_index, file_id, 3 more }` + - `Error object { code, message, type }` - - `container_id: string` + An error produced while attempting moderation for the response input or output. - The ID of the container. + - `code: string` - - `end_index: number` + The error code. - The index of the last character of the citation in the message. + - `message: string` - - `file_id: string` + The error message. - The ID of the container file. + - `type: "error"` - - `filename: string` + The object type, which was always `error` for moderation failures. - The filename of the container file cited. + - `"error"` - - `start_index: number` + - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` - The index of the first character of the citation in the message. + Moderation for the response output. - - `type: "container_file_citation"` + - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` - The citation type. Always `container_file_citation`. + A moderation result produced for the response input or output. - - `"container_file_citation"` + - `categories: map[boolean]` - - `type: "multi_agent_call_output"` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - The item type. Always `multi_agent_call_output`. + - `category_applied_input_types: map[array of "text" or "image"]` - - `"multi_agent_call_output"` + Which modalities of input are reflected by the score for each category. - - `id: optional string` + - `"text"` - The unique ID of this multi-agent call output. + - `"image"` - - `agent: optional object { agent_name }` + - `category_scores: map[number]` - The agent that produced this item. + A dictionary of moderation categories to scores. - - `agent_name: string` + - `flagged: boolean` - The canonical name of the agent that produced this item. + A boolean indicating whether the content was flagged by any category. - - `ToolSearchCall object { arguments, type, id, 4 more }` + - `model: string` - - `arguments: unknown` + The moderation model that produced this result. - The arguments supplied to the tool search call. + - `type: "moderation_result"` - - `type: "tool_search_call"` + The object type, which was always `moderation_result` for successful moderation results. - The item type. Always `tool_search_call`. + - `"moderation_result"` - - `"tool_search_call"` + - `Error object { code, message, type }` - - `id: optional string` + An error produced while attempting moderation for the response input or output. - The unique ID of this tool search call. + - `code: string` - - `agent: optional object { agent_name }` + The error code. - The agent that produced this item. + - `message: string` - - `agent_name: string` + The error message. - The canonical name of the agent that produced this item. + - `type: "error"` - - `call_id: optional string` + The object type, which was always `error` for moderation failures. - The unique ID of the tool search call generated by the model. + - `"error"` - - `execution: optional "server" or "client"` + - `output_text: optional string` - Whether tool search was executed by the server or by the client. + 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. - - `"server"` + - `previous_response_id: optional string` - - `"client"` + 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`. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `prompt: optional BetaResponsePrompt` - The status of the tool search call. + Reference to a prompt template and its variables. + [Learn more](/docs/guides/text?api-mode=responses#reusable-prompts). - - `"in_progress"` + - `id: string` - - `"completed"` + The unique identifier of the prompt template to use. - - `"incomplete"` + - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` - - `ToolSearchOutput object { tools, type, id, 4 more }` + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. - - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` + - `string` - The loaded tool definitions returned by the tool search output. + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `Function object { name, parameters, strict, 5 more }` + A 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). + - `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 function to call. + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `parameters: map[unknown]` + A file input to the model. - A JSON schema object describing the parameters of the function. + - `version: optional string` - - `strict: boolean` + Optional version of the prompt template. - Whether strict parameter validation is enforced for this function tool. + - `prompt_cache_key: optional string` - - `type: "function"` + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](/docs/guides/prompt-caching). - The type of the function tool. Always `function`. + - `prompt_cache_options: optional object { mode, ttl }` - - `"function"` + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `mode: "implicit" or "explicit"` - The tool invocation context(s). + Whether implicit prompt-cache breakpoints were enabled. - - `"direct"` + - `"implicit"` - - `"programmatic"` + - `"explicit"` - - `defer_loading: optional boolean` + - `ttl: "30m"` - Whether this function is deferred and loaded via tool search. + The minimum lifetime applied to each cache breakpoint. - - `description: optional string` + - `"30m"` - A description of the function. Used by the model to determine whether or not to call the function. + - `prompt_cache_retention: optional "in_memory" or "24h"` - - `output_schema: optional map[unknown]` + Deprecated. Use `prompt_cache_options.ttl` instead. - A JSON schema object describing the JSON value encoded in string outputs for this function. + 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. - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - 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). + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - - `type: "file_search"` + - `"in_memory"` - The type of the file search tool. Always `file_search`. + - `"24h"` - - `"file_search"` + - `reasoning: optional object { context, effort, generate_summary, 2 more }` - - `vector_store_ids: array of string` + **gpt-5 and o-series models only** - The IDs of the vector stores to search. + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - `filters: optional object { key, type, value } or object { filters, type }` + - `context: optional "auto" or "current_turn" or "all_turns"` - A filter to apply. + Controls which reasoning items are rendered back to the model on later turns. + When returned on a response, this is the effective reasoning context mode + used for the response. - - `ComparisonFilter object { key, type, value }` + - `"auto"` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `"current_turn"` - - `key: string` + - `"all_turns"` - The key to compare against the value. + - `effort: optional "none" or "minimal" or "low" or 4 more` - - `type: "eq" or "ne" or "gt" or 5 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. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `"none"` - - `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 + - `"minimal"` - - `"eq"` + - `"low"` - - `"ne"` + - `"medium"` - - `"gt"` + - `"high"` - - `"gte"` + - `"xhigh"` - - `"lt"` + - `"max"` - - `"lte"` + - `generate_summary: optional "auto" or "concise" or "detailed"` - - `"in"` + **Deprecated:** use `summary` instead. - - `"nin"` + 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`. - - `value: string or number or boolean or array of string or number` + - `"auto"` - The value to compare against the attribute key; supports string, number, or boolean types. + - `"concise"` - - `string` + - `"detailed"` - - `number` + - `mode: optional string or "standard" or "pro"` - - `boolean` + Controls the reasoning execution mode for the request. - - `array of string or number` + When returned on a response, this is the effective execution mode. - `string` - - `number` - - - `CompoundFilter object { filters, type }` + - `"standard" or "pro"` - Combine multiple filters using `and` or `or`. + Controls the reasoning execution mode for the request. - - `filters: array of object { key, type, value } or unknown` + When returned on a response, this is the effective execution mode. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `"standard"` - - `ComparisonFilter object { key, type, value }` + - `"pro"` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `summary: optional "auto" or "concise" or "detailed"` - - `key: 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 key to compare against the value. + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - - `type: "eq" or "ne" or "gt" or 5 more` + - `"auto"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `"concise"` - - `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 + - `"detailed"` - - `"eq"` + - `safety_identifier: optional string` - - `"ne"` + 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). - - `"gt"` + - `service_tier: optional "auto" or "default" or "flex" or 2 more` - - `"gte"` + Specifies the processing type used for serving the request. - - `"lt"` + - 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'. - - `"lte"` + 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. - - `"in"` + - `"auto"` - - `"nin"` + - `"default"` - - `value: string or number or boolean or array of string or number` + - `"flex"` - The value to compare against the attribute key; supports string, number, or boolean types. + - `"scale"` - - `string` + - `"priority"` - - `number` + - `status: optional BetaResponseStatus` - - `boolean` + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - - `array of string or number` + - `"completed"` - - `string` + - `"failed"` - - `number` + - `"in_progress"` - - `unknown` + - `"cancelled"` - - `type: "and" or "or"` + - `"queued"` - Type of operation: `and` or `or`. + - `"incomplete"` - - `"and"` + - `text: optional BetaResponseTextConfig` - - `"or"` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - - `max_num_results: optional number` + - [Text inputs and outputs](/docs/guides/text) + - [Structured Outputs](/docs/guides/structured-outputs) - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `format: optional BetaResponseFormatTextConfig` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + An object specifying the format that the model must output. - Ranking options for search. + 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). - - `hybrid_search: optional object { embedding_weight, text_weight }` + The default format is `{ "type": "text" }` with no additional options. - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + **Not recommended for gpt-4o and newer models:** - - `embedding_weight: 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 weight of the embedding in the reciprocal ranking fusion. + - `Text object { type }` - - `text_weight: number` + Default response format. Used to generate text responses. - The weight of the text in the reciprocal ranking fusion. + - `type: "text"` - - `ranker: optional "auto" or "default-2024-11-15"` + The type of response format being defined. Always `text`. - The ranker to use for the file search. + - `"text"` - - `"auto"` + - `BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` - - `"default-2024-11-15"` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - - `score_threshold: optional number` + - `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 name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - - `Computer object { type }` + - `schema: map[unknown]` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `type: "computer"` + - `type: "json_schema"` - The type of the computer tool. Always `computer`. + The type of response format being defined. Always `json_schema`. - - `"computer"` + - `"json_schema"` - - `ComputerUsePreview object { display_height, display_width, environment, type }` + - `description: optional string` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `display_height: number` + - `strict: optional boolean` - The height of the computer display. + 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). - - `display_width: number` + - `JSONObject object { type }` - The width of the computer display. + 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. - - `environment: "windows" or "mac" or "linux" or 2 more` + - `type: "json_object"` - The type of computer environment to control. + The type of response format being defined. Always `json_object`. - - `"windows"` + - `"json_object"` - - `"mac"` + - `verbosity: optional "low" or "medium" or "high"` - - `"linux"` + 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`. - - `"ubuntu"` + - `"low"` - - `"browser"` + - `"medium"` - - `type: "computer_use_preview"` + - `"high"` - The type of the computer use tool. Always `computer_use_preview`. + - `top_logprobs: optional number` - - `"computer_use_preview"` + 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. - - `WebSearch object { type, filters, search_context_size, user_location }` + - `truncation: optional "auto" or "disabled"` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The truncation strategy to use for the model response. - - `type: "web_search" or "web_search_2025_08_26"` + - `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 web search tool. One of `web_search` or `web_search_2025_08_26`. + - `"auto"` - - `"web_search"` + - `"disabled"` - - `"web_search_2025_08_26"` + - `usage: optional BetaResponseUsage` - - `filters: optional object { allowed_domains }` + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - Filters for the search. + - `input_tokens: number` - - `allowed_domains: optional array of string` + The number of input tokens. - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `input_tokens_details: object { cache_write_tokens, cached_tokens }` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + A detailed breakdown of the input tokens. - - `search_context_size: optional "low" or "medium" or "high"` + - `cache_write_tokens: 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 number of input tokens that were written to the cache. - - `"low"` + - `cached_tokens: number` - - `"medium"` + The number of tokens that were retrieved from the cache. + [More on prompt caching](/docs/guides/prompt-caching). - - `"high"` + - `output_tokens: number` - - `user_location: optional object { city, country, region, 2 more }` + The number of output tokens. - The approximate location of the user. + - `output_tokens_details: object { reasoning_tokens }` - - `city: optional string` + A detailed breakdown of the output tokens. - Free text input for the city of the user, e.g. `San Francisco`. + - `reasoning_tokens: number` - - `country: optional string` + The number of reasoning tokens. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `total_tokens: number` - - `region: optional string` + The total number of tokens used. - Free text input for the region of the user, e.g. `California`. + - `user: optional string` - - `timezone: 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 [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 for this event. - The type of location approximation. Always `approximate`. + - `type: "response.created"` - - `"approximate"` + The type of the event. Always `response.created`. - - `Mcp object { server_label, type, allowed_callers, 9 more }` + - `"response.created"` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/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`. +### Beta Response Custom Tool Call Input Delta Event - - `"mcp"` +- `BetaResponseCustomToolCallInputDeltaEvent object { delta, item_id, output_index, 3 more }` - - `allowed_callers: optional array of "direct" or "programmatic"` + Event representing a delta (partial update) to the input of a custom tool call. - The tool invocation context(s). + - `delta: string` - - `"direct"` + The incremental input data (delta) for the custom tool call. - - `"programmatic"` + - `item_id: string` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + Unique identifier for the API item associated with this event. - List of allowed tool names or a filter object. + - `output_index: number` - - `McpAllowedTools = array of string` + The index of the output this delta applies to. - A string array of allowed tool names + - `sequence_number: number` - - `McpToolFilter object { read_only, tool_names }` + The sequence number of this event. - A filter object to specify which tools are allowed. + - `type: "response.custom_tool_call_input.delta"` - - `read_only: optional boolean` + The event type identifier. - 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. + - `"response.custom_tool_call_input.delta"` - - `tool_names: optional array of string` + - `agent: optional object { agent_name }` - List of allowed tool names. + The agent that owns this multi-agent streaming event. - - `authorization: optional string` + - `agent_name: 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 canonical name of the agent that produced this item. - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` +### Beta Response Custom Tool Call Input Done Event - 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). +- `BetaResponseCustomToolCallInputDoneEvent object { input, item_id, output_index, 3 more }` - Currently supported `connector_id` values are: + Event indicating that input for a custom tool call is complete. - - 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` + - `input: string` - - `"connector_dropbox"` + The complete input data for the custom tool call. - - `"connector_gmail"` + - `item_id: string` - - `"connector_googlecalendar"` + Unique identifier for the API item associated with this event. - - `"connector_googledrive"` + - `output_index: number` - - `"connector_microsoftteams"` + The index of the output this event applies to. - - `"connector_outlookcalendar"` + - `sequence_number: number` - - `"connector_outlookemail"` + The sequence number of this event. - - `"connector_sharepoint"` + - `type: "response.custom_tool_call_input.done"` - - `defer_loading: optional boolean` + The event type identifier. - Whether this MCP tool is deferred and discovered via tool search. + - `"response.custom_tool_call_input.done"` - - `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 }` +### Beta Response Error - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. +- `BetaResponseError object { code, message }` - - `always: optional object { read_only, tool_names }` + An error object returned when the model fails to generate a Response. - A filter object to specify which tools are allowed. + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 16 more` - - `read_only: optional boolean` + The error code for the 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. + - `"server_error"` - - `tool_names: optional array of string` + - `"rate_limit_exceeded"` - List of allowed tool names. + - `"invalid_prompt"` - - `never: optional object { read_only, tool_names }` + - `"bio_policy"` - A filter object to specify which tools are allowed. + - `"vector_store_timeout"` - - `read_only: optional boolean` + - `"invalid_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. + - `"invalid_image_format"` - - `tool_names: optional array of string` + - `"invalid_base64_image"` - List of allowed tool names. + - `"invalid_image_url"` - - `McpToolApprovalSetting = "always" or "never"` + - `"image_too_large"` - 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. + - `"image_too_small"` - - `"always"` + - `"image_parse_error"` - - `"never"` + - `"image_content_policy_violation"` - - `server_description: optional string` + - `"invalid_image_mode"` - Optional description of the MCP server, used to provide more context. + - `"image_file_too_large"` - - `server_url: optional string` + - `"unsupported_image_media_type"` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `"empty_image_file"` - - `tunnel_id: optional string` + - `"failed_to_download_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. + - `"image_file_not_found"` - - `CodeInterpreter object { container, type, allowed_callers }` + - `message: string` - A tool that runs Python code to help generate a response to a prompt. + A human-readable description of the error. - - `container: string or object { type, file_ids, memory_limit, network_policy }` +### Beta Response Error Event - 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. +- `BetaResponseErrorEvent object { code, message, param, 3 more }` - - `string` + Emitted when an error occurs. - The container ID. + - `code: string` - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + The error code. - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `message: string` - - `type: "auto"` + The error message. - Always `auto`. + - `param: string` - - `"auto"` + The error parameter. - - `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: "error"` - The memory limit for the code interpreter container. + The type of the event. Always `error`. - - `"1g"` + - `"error"` - - `"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. +### Beta Response Failed Event - - `BetaContainerNetworkPolicyDisabled object { type }` +- `BetaResponseFailedEvent object { response, sequence_number, type, agent }` - - `type: "disabled"` + An event that is emitted when a response fails. - Disable outbound network access. Always `disabled`. + - `response: BetaResponse` - - `"disabled"` + The response that failed. - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `id: string` - - `allowed_domains: array of string` + Unique identifier for this Response. - A list of allowed domains when type is `allowlist`. + - `created_at: number` - - `type: "allowlist"` + Unix timestamp (in seconds) of when this Response was created. - Allow outbound network access only to specified domains. Always `allowlist`. + - `error: BetaResponseError` - - `"allowlist"` + An error object returned when the model fails to generate a Response. - - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 16 more` - Optional domain-scoped secrets for allowlisted domains. + The error code for the response. - - `domain: string` + - `"server_error"` - The domain associated with the secret. + - `"rate_limit_exceeded"` - - `name: string` + - `"invalid_prompt"` - The name of the secret to inject for the domain. + - `"bio_policy"` - - `value: string` + - `"vector_store_timeout"` - The secret value to inject for the domain. + - `"invalid_image"` - - `type: "code_interpreter"` + - `"invalid_image_format"` - The type of the code interpreter tool. Always `code_interpreter`. + - `"invalid_base64_image"` - - `"code_interpreter"` + - `"invalid_image_url"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"image_too_large"` - The tool invocation context(s). + - `"image_too_small"` - - `"direct"` + - `"image_parse_error"` - - `"programmatic"` + - `"image_content_policy_violation"` - - `ProgrammaticToolCalling object { type }` + - `"invalid_image_mode"` - - `type: "programmatic_tool_calling"` + - `"image_file_too_large"` - The type of the tool. Always `programmatic_tool_calling`. + - `"unsupported_image_media_type"` - - `"programmatic_tool_calling"` + - `"empty_image_file"` - - `ImageGeneration object { type, action, background, 9 more }` + - `"failed_to_download_image"` - A tool that generates images using the GPT image models. + - `"image_file_not_found"` - - `type: "image_generation"` + - `message: string` - The type of the image generation tool. Always `image_generation`. + A human-readable description of the error. - - `"image_generation"` + - `incomplete_details: object { reason }` - - `action: optional "generate" or "edit" or "auto"` + Details about why the response is incomplete. - Whether to generate a new image or edit an existing image. Default: `auto`. + - `reason: optional "max_output_tokens" or "content_filter"` - - `"generate"` + The reason why the response is incomplete. - - `"edit"` + - `"max_output_tokens"` - - `"auto"` + - `"content_filter"` - - `background: optional "transparent" or "opaque" or "auto"` + - `instructions: string or array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + A system (or developer) message inserted into the model's context. - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + 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. - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `string` - - `"transparent"` + A text input to the model, equivalent to a text input with the + `developer` role. - - `"opaque"` + - `InputItemList = array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` - - `"auto"` + A list of one or many input items to the model, containing + different content types. - - `input_fidelity: optional "high" or "low"` + - `BetaEasyInputMessage object { content, role, phase, 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`. + 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. - - `"high"` + - `content: string or BetaResponseInputMessageContentList` - - `"low"` + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `input_image_mask: optional object { file_id, image_url }` + - `TextInput = string` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + A text input to the model. - - `file_id: optional string` + - `BetaResponseInputMessageContentList = array of BetaResponseInputContent` - File ID for the mask image. + A list of one or many input items to the model, containing different content + types. - - `image_url: optional string` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - Base64-encoded mask image. + A text input to the model. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `text: string` - The image generation model to use. Default: `gpt-image-1`. + The text input to the model. - - `string` + - `type: "input_text"` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + The type of the input item. Always `input_text`. - The image generation model to use. Default: `gpt-image-1`. + - `"input_text"` - - `"gpt-image-1"` + - `prompt_cache_breakpoint: optional object { mode }` - - `"gpt-image-1-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. - - `"gpt-image-2"` + - `mode: "explicit"` - - `"gpt-image-2-2026-04-21"` + The breakpoint mode. Always `explicit`. - - `"gpt-image-1.5"` + - `"explicit"` - - `"chatgpt-image-latest"` + - `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`. + - `detail: "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`. - `"low"` - - `output_compression: optional number` - - Compression level for the output image. Default: 100. + - `"high"` - - `output_format: optional "png" or "webp" or "jpeg"` + - `"auto"` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `"original"` - - `"png"` + - `type: "input_image"` - - `"webp"` + The type of the input item. Always `input_image`. - - `"jpeg"` + - `"input_image"` - - `partial_images: optional number` + - `file_id: optional string` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + The ID of the file to be sent to the model. - - `quality: optional "low" or "medium" or "high" or "auto"` + - `image_url: optional string` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `"low"` + - `prompt_cache_breakpoint: optional object { mode }` - - `"medium"` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `"high"` + - `mode: "explicit"` - - `"auto"` + The breakpoint mode. Always `explicit`. - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `"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`. + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `string` + A file input to the model. - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `type: "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`. + The type of the input item. Always `input_file`. - - `"1024x1024"` + - `"input_file"` - - `"1024x1536"` + - `detail: optional "auto" or "low" or "high"` - - `"1536x1024"` + 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"` - - `LocalShell object { type }` + - `"low"` - A tool that allows the model to execute shell commands in a local environment. + - `"high"` - - `type: "local_shell"` + - `file_data: optional string` - The type of the local shell tool. Always `local_shell`. + The content of the file to be sent to the model. - - `"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. + - `file_url: optional string` - - `type: "shell"` + The URL of the file to be sent to the model. - The type of the shell tool. Always `shell`. + - `filename: optional string` - - `"shell"` + 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`. - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + - `"explicit"` - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `role: "user" or "assistant" or "system" or "developer"` - - `type: "container_auto"` + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - Automatically creates a container for this request + - `"user"` - - `"container_auto"` + - `"assistant"` - - `file_ids: optional array of string` + - `"system"` - An optional list of uploaded files to make available to your code. + - `"developer"` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `phase: optional "commentary" or "final_answer"` - The memory limit for the container. + 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. - - `"1g"` + - `"commentary"` - - `"4g"` + - `"final_answer"` - - `"16g"` + - `type: optional "message"` - - `"64g"` + The type of the message input. Always `message`. - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `"message"` - Network access policy for the container. + - `Message object { content, role, agent, 2 more }` - - `BetaContainerNetworkPolicyDisabled object { 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. - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `content: BetaResponseInputMessageContentList` - - `skills: optional array of BetaSkillReference or BetaInlineSkill` + A list of one or many input items to the model, containing different content + types. - An optional list of skills referenced by id or inline data. + - `role: "user" or "system" or "developer"` - - `BetaSkillReference object { skill_id, type, version }` + The role of the message input. One of `user`, `system`, or `developer`. - - `skill_id: string` + - `"user"` - The ID of the referenced skill. + - `"system"` - - `type: "skill_reference"` + - `"developer"` - References a skill created with the /v1/skills endpoint. + - `agent: optional object { agent_name }` - - `"skill_reference"` + The agent that produced this item. - - `version: optional string` + - `agent_name: string` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + The canonical name of the agent that produced this item. - - `BetaInlineSkill object { description, name, source, type }` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `description: string` + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The description of the skill. + - `"in_progress"` - - `name: string` + - `"completed"` - The name of the skill. + - `"incomplete"` - - `source: BetaInlineSkillSource` + - `type: optional "message"` - Inline skill payload + The type of the message input. Always set to `message`. - - `data: string` + - `"message"` - Base64-encoded skill zip bundle. + - `BetaResponseOutputMessage object { id, content, role, 4 more }` - - `media_type: "application/zip"` + An output message from the model. - The media type of the inline skill payload. Must be `application/zip`. + - `id: string` - - `"application/zip"` + The unique ID of the output message. - - `type: "base64"` + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - The type of the inline skill source. Must be `base64`. + The content of the output message. - - `"base64"` + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - - `type: "inline"` + A text output from the model. - Defines an inline skill for this request. + - `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 }` - - `"inline"` + The annotations of the text output. - - `BetaLocalEnvironment object { type, skills }` + - `FileCitation object { file_id, filename, index, type }` - - `type: "local"` + A citation to a file. - Use a local computer environment. + - `file_id: string` - - `"local"` + The ID of the file. - - `skills: optional array of BetaLocalSkill` + - `filename: string` - An optional list of skills. + The filename of the file cited. - - `description: string` + - `index: number` - The description of the skill. + The index of the file in the list of files. - - `name: string` + - `type: "file_citation"` - The name of the skill. + The type of the file citation. Always `file_citation`. - - `path: string` + - `"file_citation"` - The path to the directory containing the skill. + - `URLCitation object { end_index, start_index, title, 2 more }` - - `BetaContainerReference object { container_id, type }` + A citation for a web resource used to generate a model response. - - `container_id: string` + - `end_index: number` - The ID of the referenced container. + The index of the last character of the URL citation in the message. - - `type: "container_reference"` + - `start_index: number` - References a container created with the /v1/containers endpoint + The index of the first character of the URL citation in the message. - - `"container_reference"` + - `title: string` - - `Custom object { name, type, allowed_callers, 3 more }` + The title of the web resource. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `type: "url_citation"` - - `name: string` + The type of the URL citation. Always `url_citation`. - The name of the custom tool, used to identify it in tool calls. + - `"url_citation"` - - `type: "custom"` + - `url: string` - The type of the custom tool. Always `custom`. + The URL of the web resource. - - `"custom"` + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - - `allowed_callers: optional array of "direct" or "programmatic"` + A citation for a container file used to generate a model response. - The tool invocation context(s). + - `container_id: string` - - `"direct"` + The ID of the container file. - - `"programmatic"` + - `end_index: number` - - `defer_loading: optional boolean` + The index of the last character of the container file citation in the message. - Whether this tool should be deferred and discovered via tool search. + - `file_id: string` - - `description: optional string` + The ID of the file. - Optional description of the custom tool, used to provide more context. + - `filename: string` - - `format: optional object { type } or object { definition, syntax, type }` + The filename of the container file cited. - The input format for the custom tool. Default is unconstrained text. + - `start_index: number` - - `Text object { type }` + The index of the first character of the container file citation in the message. - Unconstrained free-form text. + - `type: "container_file_citation"` - - `type: "text"` + The type of the container file citation. Always `container_file_citation`. - Unconstrained text format. Always `text`. + - `"container_file_citation"` - - `"text"` + - `FilePath object { file_id, index, type }` - - `Grammar object { definition, syntax, type }` + A path to a file. - A grammar defined by the user. + - `file_id: string` - - `definition: string` + The ID of the file. - The grammar definition. + - `index: number` - - `syntax: "lark" or "regex"` + The index of the file in the list of files. - The syntax of the grammar definition. One of `lark` or `regex`. + - `type: "file_path"` - - `"lark"` + The type of the file path. Always `file_path`. - - `"regex"` + - `"file_path"` - - `type: "grammar"` + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - Grammar format. Always `grammar`. + - `token: string` - - `"grammar"` + - `bytes: array of number` - - `Namespace object { description, name, tools, type }` + - `logprob: number` - Groups function/custom tools under a shared namespace. + - `top_logprobs: array of object { token, bytes, logprob }` - - `description: string` + - `token: string` - A description of the namespace shown to the model. + - `bytes: array of number` - - `name: string` + - `logprob: number` - The namespace name used in tool calls (for example, `crm`). + - `text: string` - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + The text output from the model. - The function/custom tools available inside this namespace. + - `type: "output_text"` - - `Function object { name, type, allowed_callers, 5 more }` + The type of the output text. Always `output_text`. - - `name: string` + - `"output_text"` - - `type: "function"` + - `BetaResponseOutputRefusal object { refusal, type }` - - `"function"` + A refusal from the model. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `refusal: string` - The tool invocation context(s). + The refusal explanation from the model. - - `"direct"` + - `type: "refusal"` - - `"programmatic"` + The type of the refusal. Always `refusal`. - - `defer_loading: optional boolean` + - `"refusal"` - Whether this function should be deferred and discovered via tool search. + - `role: "assistant"` - - `description: optional string` + The role of the output message. Always `assistant`. - - `output_schema: optional map[unknown]` + - `"assistant"` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `status: "in_progress" or "completed" or "incomplete"` - - `parameters: optional unknown` + The status of the 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](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `type: "message"` - - `name: string` + The type of the output message. Always `message`. - The name of the custom tool, used to identify it in tool calls. + - `"message"` - - `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). + - `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"` - - `defer_loading: optional boolean` + - `"final_answer"` - Whether this tool should be deferred and discovered via tool search. + - `FileSearchCall object { id, queries, status, 3 more }` - - `description: optional string` + The results of a file search tool call. See the + [file search guide](/docs/guides/tools-file-search) for more information. - 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 file search tool call. - The input format for the custom tool. Default is unconstrained text. + - `queries: array of string` - - `Text object { type }` + The queries used to search for files. - Unconstrained free-form text. + - `status: "in_progress" or "searching" or "completed" or 2 more` - - `type: "text"` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - Unconstrained text format. Always `text`. + - `"in_progress"` - - `"text"` + - `"searching"` - - `Grammar object { definition, syntax, type }` + - `"completed"` - A grammar defined by the user. + - `"incomplete"` - - `definition: string` + - `"failed"` - The grammar definition. + - `type: "file_search_call"` - - `syntax: "lark" or "regex"` + The type of the file search tool call. Always `file_search_call`. - The syntax of the grammar definition. One of `lark` or `regex`. + - `"file_search_call"` - - `"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"` + - `results: optional array of object { attributes, file_id, filename, 2 more }` - - `type: "namespace"` + The results of the file search tool call. - The type of the tool. Always `namespace`. + - `attributes: optional map[string or number or boolean]` - - `"namespace"` + 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. - - `ToolSearch object { type, description, execution, parameters }` + - `string` - Hosted or BYOT tool search configuration for deferred tools. + - `number` - - `type: "tool_search"` + - `boolean` - The type of the tool. Always `tool_search`. + - `file_id: optional string` - - `"tool_search"` + The unique ID of the file. - - `description: optional string` + - `filename: optional string` - Description shown to the model for a client-executed tool search tool. + The name of the file. - - `execution: optional "server" or "client"` + - `score: optional number` - Whether tool search is executed by the server or by the client. + The relevance score of the file - a value between 0 and 1. - - `"server"` + - `text: optional string` - - `"client"` + The text that was retrieved from the file. - - `parameters: optional unknown` + - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` - Parameter schema for a client-executed tool search tool. + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + - `id: string` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The unique ID of the computer call. - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `call_id: string` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + An identifier used when responding to the tool call with output. - - `"web_search_preview"` + - `pending_safety_checks: array of object { id, code, message }` - - `"web_search_preview_2025_03_11"` + The pending safety checks for the computer call. - - `search_content_types: optional array of "text" or "image"` + - `id: string` - - `"text"` + The ID of the pending safety check. - - `"image"` + - `code: optional string` - - `search_context_size: optional "low" or "medium" or "high"` + The type of the pending safety check. - 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. + - `message: optional string` - - `"low"` + Details about the pending safety check. - - `"medium"` + - `status: "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. - - `user_location: optional object { type, city, country, 2 more }` + - `"in_progress"` - The user's location. + - `"completed"` - - `type: "approximate"` + - `"incomplete"` - The type of location approximation. Always `approximate`. + - `type: "computer_call"` - - `"approximate"` + The type of the computer call. Always `computer_call`. - - `city: optional string` + - `"computer_call"` - Free text input for the city of the user, e.g. `San Francisco`. + - `action: optional BetaComputerAction` - - `country: optional string` + A click action. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `Click object { button, type, x, 2 more }` - - `region: optional string` + A click action. - Free text input for the region of the user, e.g. `California`. + - `button: "left" or "right" or "wheel" or 2 more` - - `timezone: optional string` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `"left"` - - `ApplyPatch object { type, allowed_callers }` + - `"right"` - Allows the assistant to create, delete, or update files using unified diffs. + - `"wheel"` - - `type: "apply_patch"` + - `"back"` - The type of the tool. Always `apply_patch`. + - `"forward"` - - `"apply_patch"` + - `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. - - `type: "tool_search_output"` + - `y: number` - The item type. Always `tool_search_output`. + The y-coordinate where the click occurred. - - `"tool_search_output"` + - `keys: optional array of string` - - `id: optional string` + The keys being held while clicking. - The unique ID of this tool search output. + - `DoubleClick object { keys, type, x, y }` - - `agent: optional object { agent_name }` + A double click action. - The agent that produced this item. + - `keys: array of string` - - `agent_name: string` + The keys being held while double-clicking. - The canonical name of the agent that produced this item. + - `type: "double_click"` - - `call_id: optional string` + Specifies the event type. For a double click action, this property is always set to `double_click`. - The unique ID of the tool search call generated by the model. + - `"double_click"` - - `execution: optional "server" or "client"` + - `x: number` - Whether tool search was executed by the server or by the client. + The x-coordinate where the double click occurred. - - `"server"` + - `y: number` - - `"client"` + The y-coordinate where the double click occurred. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `Drag object { path, type, keys }` - The status of the tool search output. + A drag action. - - `"in_progress"` + - `path: array of object { x, y }` - - `"completed"` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `"incomplete"` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `AdditionalTools object { role, tools, type, 2 more }` + - `x: number` - - `role: "developer"` + The x-coordinate. - The role that provided the additional tools. Only `developer` is supported. + - `y: number` - - `"developer"` + The y-coordinate. - - `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: "drag"` - A list of additional tools made available at this item. + Specifies the event type. For a drag action, this property is always set to `drag`. - - `Function object { name, parameters, strict, 5 more }` + - `"drag"` - 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). + - `keys: optional array of string` - - `name: string` + The keys being held while dragging the mouse. - The name of the function to call. + - `Keypress object { keys, type }` - - `parameters: map[unknown]` + A collection of keypresses the model would like to perform. - A JSON schema object describing the parameters of the function. + - `keys: array of string` - - `strict: boolean` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - Whether strict parameter validation is enforced for this function tool. + - `type: "keypress"` - - `type: "function"` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - The type of the function tool. Always `function`. + - `"keypress"` - - `"function"` + - `Move object { type, x, y, keys }` - - `allowed_callers: optional array of "direct" or "programmatic"` + A mouse move action. - The tool invocation context(s). + - `type: "move"` - - `"direct"` + Specifies the event type. For a move action, this property is always set to `move`. - - `"programmatic"` + - `"move"` - - `defer_loading: optional boolean` + - `x: number` - Whether this function is deferred and loaded via tool search. + The x-coordinate to move to. - - `description: optional string` + - `y: number` - A description of the function. Used by the model to determine whether or not to call the function. + The y-coordinate to move to. - - `output_schema: optional map[unknown]` + - `keys: optional array of string` - A JSON schema object describing the JSON value encoded in string outputs for this function. + The keys being held while moving the mouse. - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + - `Screenshot object { 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). + A screenshot action. - - `type: "file_search"` + - `type: "screenshot"` - The type of the file search tool. Always `file_search`. + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `"file_search"` + - `"screenshot"` - - `vector_store_ids: array of string` + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - The IDs of the vector stores to search. + A scroll action. - - `filters: optional object { key, type, value } or object { filters, type }` + - `scroll_x: number` - A filter to apply. + 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"` + + - `actions: optional BetaComputerActionList` + + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `CompoundFilter object { filters, type }` + - `Click object { button, type, x, 2 more }` - Combine multiple filters using `and` or `or`. + A click action. - - `filters: array of object { key, type, value } or unknown` + - `DoubleClick object { keys, type, x, y }` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + A double click action. - - `ComparisonFilter object { key, type, value }` + - `Drag object { path, type, keys }` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + A drag action. - - `key: string` + - `Keypress object { keys, type }` - The key to compare against the value. + A collection of keypresses the model would like to perform. - - `type: "eq" or "ne" or "gt" or 5 more` + - `Move object { type, x, y, keys }` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + A mouse move 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 + - `Screenshot object { type }` - - `"eq"` + A screenshot action. - - `"ne"` + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - - `"gt"` + A scroll action. - - `"gte"` + - `Type object { text, type }` - - `"lt"` + An action to type in text. - - `"lte"` + - `Wait object { type }` - - `"in"` + A wait action. - - `"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` + - `ComputerCallOutput object { call_id, output, type, 4 more }` - - `boolean` + The output of a computer tool call. - - `array of string or number` + - `call_id: string` - - `string` + The ID of the computer tool call that produced the output. - - `number` + - `output: BetaResponseComputerToolCallOutputScreenshot` - - `unknown` + A computer screenshot image used with the computer use tool. - - `type: "and" or "or"` + - `type: "computer_screenshot"` - Type of operation: `and` or `or`. + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `"and"` + - `"computer_screenshot"` - - `"or"` + - `file_id: optional string` - - `max_num_results: optional number` + The identifier of an uploaded file that contains the screenshot. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `image_url: optional string` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + The URL of the screenshot image. - Ranking options for search. + - `type: "computer_call_output"` - - `hybrid_search: optional object { embedding_weight, text_weight }` + The type of the computer tool call output. Always `computer_call_output`. - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `"computer_call_output"` - - `embedding_weight: number` + - `id: optional string` - The weight of the embedding in the reciprocal ranking fusion. + The ID of the computer tool call output. - - `text_weight: number` + - `acknowledged_safety_checks: optional array of object { id, code, message }` - The weight of the text in the reciprocal ranking fusion. + The safety checks reported by the API that have been acknowledged by the developer. - - `ranker: optional "auto" or "default-2024-11-15"` + - `id: string` - The ranker to use for the file search. + The ID of the pending safety check. - - `"auto"` + - `code: optional string` - - `"default-2024-11-15"` + The type of the pending safety check. - - `score_threshold: optional number` + - `message: optional string` - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + Details about the pending safety check. - - `Computer object { 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. - - `type: "computer"` + - `agent_name: string` - The type of the computer tool. Always `computer`. + The canonical name of the agent that produced this item. - - `"computer"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `ComputerUsePreview object { display_height, display_width, environment, 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"` - - `display_height: number` + - `"completed"` - The height of the computer display. + - `"incomplete"` - - `display_width: number` + - `WebSearchCall object { id, action, status, 2 more }` - The width of the computer display. + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. - - `environment: "windows" or "mac" or "linux" or 2 more` + - `id: string` - The type of computer environment to control. + The unique ID of the web search tool call. - - `"windows"` + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - - `"mac"` + 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). - - `"linux"` + - `Search object { type, queries, query, sources }` - - `"ubuntu"` + Action type "search" - Performs a web search query. - - `"browser"` + - `type: "search"` - - `type: "computer_use_preview"` + The action type. - The type of the computer use tool. Always `computer_use_preview`. + - `"search"` - - `"computer_use_preview"` + - `queries: optional array of string` - - `WebSearch object { type, filters, search_context_size, user_location }` + The search queries. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `query: optional string` - - `type: "web_search" or "web_search_2025_08_26"` + The search query. - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `sources: optional array of object { type, url }` - - `"web_search"` + The sources used in the search. - - `"web_search_2025_08_26"` + - `type: "url"` - - `filters: optional object { allowed_domains }` + The type of source. Always `url`. - Filters for the search. + - `"url"` - - `allowed_domains: optional array of string` + - `url: string` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + The URL of the source. - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `OpenPage object { type, url }` - - `search_context_size: optional "low" or "medium" or "high"` + Action type "open_page" - Opens a specific URL from search results. - 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: "open_page"` - - `"low"` + The action type. - - `"medium"` + - `"open_page"` - - `"high"` + - `url: optional string` - - `user_location: optional object { city, country, region, 2 more }` + The URL opened by the model. - The approximate location of the user. + - `FindInPage object { pattern, type, url }` - - `city: optional string` + Action type "find_in_page": Searches for a pattern within a loaded page. - Free text input for the city of the user, e.g. `San Francisco`. + - `pattern: string` - - `country: optional string` + The pattern or text to search for within the page. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `type: "find_in_page"` - - `region: optional string` + The action type. - Free text input for the region of the user, e.g. `California`. + - `"find_in_page"` - - `timezone: optional string` + - `url: string` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The URL of the page searched for the pattern. - - `type: optional "approximate"` + - `status: "in_progress" or "searching" or "completed" or "failed"` - The type of location approximation. Always `approximate`. + The status of the web search tool call. - - `"approximate"` + - `"in_progress"` - - `Mcp object { server_label, type, allowed_callers, 9 more }` + - `"searching"` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `"completed"` - - `server_label: string` + - `"failed"` - A label for this MCP server, used to identify it in tool calls. + - `type: "web_search_call"` - - `type: "mcp"` + The type of the web search tool call. Always `web_search_call`. - The type of the MCP tool. Always `mcp`. + - `"web_search_call"` - - `"mcp"` + - `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"` + - `FunctionCall object { arguments, call_id, name, 6 more }` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. - List of allowed tool names or a filter object. + - `arguments: string` - - `McpAllowedTools = array of string` + A JSON string of the arguments to pass to the function. - A string array of allowed tool names + - `call_id: string` - - `McpToolFilter object { read_only, tool_names }` + The unique ID of the function tool call generated by the model. - A filter object to specify which tools are allowed. + - `name: string` - - `read_only: optional boolean` + The name 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. + - `type: "function_call"` - - `tool_names: optional array of string` + The type of the function tool call. Always `function_call`. - List of allowed tool names. + - `"function_call"` - - `authorization: optional string` + - `id: 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 unique ID of the function tool call. - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + - `agent: optional object { agent_name }` - 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + The agent that produced this item. - Currently supported `connector_id` values are: + - `agent_name: string` - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + The canonical name of the agent that produced this item. - - `"connector_dropbox"` + - `caller: optional object { type } or object { caller_id, type }` - - `"connector_gmail"` + The execution context that produced this tool call. - - `"connector_googlecalendar"` + - `Direct object { type }` - - `"connector_googledrive"` + - `type: "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. + - `"program"` - - `headers: optional map[string]` + - `namespace: optional string` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + The namespace of the function to run. - - `require_approval: optional object { always, never } or "always" or "never"` + - `status: optional "in_progress" or "completed" or "incomplete"` - Specify which of the MCP server's tools require approval. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `McpToolApprovalFilter object { always, never }` + - `"in_progress"` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `"completed"` - - `always: optional object { read_only, tool_names }` + - `"incomplete"` - A filter object to specify which tools are allowed. + - `FunctionCallOutput object { call_id, output, type, 4 more }` - - `read_only: optional boolean` + The output of a 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. + - `call_id: string` - - `tool_names: optional array of string` + The unique ID of the function tool call generated by the model. - List of allowed tool names. + - `output: string or array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` - - `never: optional object { read_only, tool_names }` + Text, image, or file output of the function tool call. - A filter object to specify which tools are allowed. + - `string` - - `read_only: optional boolean` + A JSON string of the output 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. + - `array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` - - `tool_names: optional array of string` + An array of content outputs (text, image, file) for the function tool call. - List of allowed tool names. + - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` - - `McpToolApprovalSetting = "always" or "never"` + A text input to the model. - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + - `text: string` - - `"always"` + The text input to the model. - - `"never"` + - `type: "input_text"` - - `server_description: optional string` + The type of the input item. Always `input_text`. - Optional description of the MCP server, used to provide more context. + - `"input_text"` - - `server_url: optional string` + - `prompt_cache_breakpoint: optional object { mode }` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `tunnel_id: optional string` + - `mode: "explicit"` - 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 breakpoint mode. Always `explicit`. - - `CodeInterpreter object { container, type, allowed_callers }` + - `"explicit"` - A tool that runs Python code to help generate a response to a prompt. + - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + An image input to the model. Learn about [image inputs](/docs/guides/vision) - 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: "input_image"` - - `string` + The type of the input item. Always `input_image`. - The container ID. + - `"input_image"` - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + - `detail: optional "low" or "high" or "auto" or "original"` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `type: "auto"` + - `"low"` - Always `auto`. + - `"high"` - `"auto"` - - `file_ids: optional array of string` - - An optional list of uploaded files to make available to your code. + - `"original"` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `file_id: optional string` - The memory limit for the code interpreter container. + The ID of the file to be sent to the model. - - `"1g"` + - `image_url: optional string` - - `"4g"` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `"16g"` + - `prompt_cache_breakpoint: optional object { mode }` - - `"64g"` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `mode: "explicit"` - Network access policy for the container. + The breakpoint mode. Always `explicit`. - - `BetaContainerNetworkPolicyDisabled object { type }` + - `"explicit"` - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `BetaResponseInputFileContent object { type, detail, file_data, 4 more }` - - `type: "code_interpreter"` + A file input to the model. - The type of the code interpreter tool. Always `code_interpreter`. + - `type: "input_file"` - - `"code_interpreter"` + The type of the input item. Always `input_file`. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"input_file"` - The tool invocation context(s). + - `detail: optional "auto" or "low" or "high"` - - `"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`. - - `"programmatic"` + - `"auto"` - - `ProgrammaticToolCalling object { type }` + - `"low"` - - `type: "programmatic_tool_calling"` + - `"high"` - The type of the tool. Always `programmatic_tool_calling`. + - `file_data: optional string` - - `"programmatic_tool_calling"` + The base64-encoded data of the file to be sent to the model. - - `ImageGeneration object { type, action, background, 9 more }` + - `file_id: optional string` - A tool that generates images using the GPT image models. + The ID of the file to be sent to the model. - - `type: "image_generation"` + - `file_url: optional string` - The type of the image generation tool. Always `image_generation`. + The URL of the file to be sent to the model. - - `"image_generation"` + - `filename: optional string` - - `action: optional "generate" or "edit" or "auto"` + The name of the file to be sent to the model. - Whether to generate a new image or edit an existing image. Default: `auto`. + - `prompt_cache_breakpoint: optional object { mode }` - - `"generate"` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `"edit"` + - `mode: "explicit"` - - `"auto"` + The breakpoint mode. Always `explicit`. - - `background: optional "transparent" or "opaque" or "auto"` + - `"explicit"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + - `type: "function_call_output"` - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + The type of the function tool call output. Always `function_call_output`. - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `"function_call_output"` - - `"transparent"` + - `id: optional string` - - `"opaque"` + The unique ID of the function tool call output. Populated when this item is returned via API. - - `"auto"` + - `agent: optional object { agent_name }` - - `input_fidelity: optional "high" or "low"` + 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`. + - `agent_name: string` - - `"high"` + The canonical name of the agent that produced this item. - - `"low"` + - `caller: optional object { type } or object { caller_id, type }` - - `input_image_mask: optional object { file_id, image_url }` + The execution context that produced this tool call. - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `Direct object { type }` - - `file_id: optional string` + - `type: "direct"` - File ID for the mask image. + The caller type. Always `direct`. - - `image_url: optional string` + - `"direct"` - Base64-encoded mask image. + - `Program object { caller_id, type }` - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `caller_id: string` - The image generation model to use. Default: `gpt-image-1`. + The call ID of the program item that produced this tool call. - - `string` + - `type: "program"` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + The caller type. Always `program`. - The image generation model to use. Default: `gpt-image-1`. + - `"program"` - - `"gpt-image-1"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"gpt-image-1-mini"` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - `"gpt-image-2"` + - `"in_progress"` - - `"gpt-image-2-2026-04-21"` + - `"completed"` - - `"gpt-image-1.5"` + - `"incomplete"` - - `"chatgpt-image-latest"` + - `AgentMessage object { author, content, recipient, 3 more }` - - `moderation: optional "auto" or "low"` + A message routed between agents. - Moderation level for the generated image. Default: `auto`. + - `author: string` - - `"auto"` + The sending agent identity. - - `"low"` + - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` - - `output_compression: optional number` + Plaintext, image, or encrypted content sent between agents. - Compression level for the output image. Default: 100. + - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` - - `output_format: optional "png" or "webp" or "jpeg"` + A text input to the model. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` - - `"png"` + An image input to the model. Learn about [image inputs](/docs/guides/vision) - - `"webp"` + - `EncryptedContent object { encrypted_content, type }` - - `"jpeg"` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `partial_images: optional number` + - `encrypted_content: string` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + Opaque encrypted content. - - `quality: optional "low" or "medium" or "high" or "auto"` + - `type: "encrypted_content"` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + The type of the input item. Always `encrypted_content`. - - `"low"` + - `"encrypted_content"` - - `"medium"` + - `recipient: string` - - `"high"` + The destination agent identity. - - `"auto"` + - `type: "agent_message"` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + The item type. Always `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`. + - `"agent_message"` - - `string` + - `id: optional string` - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + The unique ID of this agent message 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: 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"` + - `MultiAgentCall object { action, arguments, call_id, 3 more }` - - `LocalShell object { type }` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - A tool that allows the model to execute shell commands in a local environment. + The multi-agent action that was executed. - - `type: "local_shell"` + - `"spawn_agent"` - The type of the local shell tool. Always `local_shell`. + - `"interrupt_agent"` - - `"local_shell"` + - `"list_agents"` - - `Shell object { type, allowed_callers, environment }` + - `"send_message"` - A tool that allows the model to execute shell commands. + - `"followup_task"` - - `type: "shell"` + - `"wait_agent"` - The type of the shell tool. Always `shell`. + - `arguments: string` - - `"shell"` + The action arguments as a JSON string. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `call_id: string` - The tool invocation context(s). + The unique ID linking this call to its output. - - `"direct"` + - `type: "multi_agent_call"` - - `"programmatic"` + The item type. Always `multi_agent_call`. - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + - `"multi_agent_call"` - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `id: optional string` - - `BetaLocalEnvironment object { type, skills }` + The unique ID of this multi-agent call. - - `BetaContainerReference object { container_id, type }` + - `agent: optional object { agent_name }` - - `Custom object { name, type, allowed_callers, 3 more }` + The agent that produced this item. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `agent_name: string` - - `name: string` + The canonical name of the agent that produced this item. - The name of the custom tool, used to identify it in tool calls. + - `MultiAgentCallOutput object { action, call_id, output, 3 more }` - - `type: "custom"` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - The type of the custom tool. Always `custom`. + The multi-agent action that produced this result. - - `"custom"` + - `"spawn_agent"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"interrupt_agent"` - The tool invocation context(s). + - `"list_agents"` - - `"direct"` + - `"send_message"` - - `"programmatic"` + - `"followup_task"` - - `defer_loading: optional boolean` + - `"wait_agent"` - Whether this tool should be deferred and discovered via tool search. + - `call_id: string` - - `description: optional string` + The unique ID of the multi-agent call. - Optional description of the custom tool, used to provide more context. + - `output: array of object { text, type, annotations }` - - `format: optional object { type } or object { definition, syntax, type }` + Text output returned by the multi-agent action. - The input format for the custom tool. Default is unconstrained text. + - `text: string` - - `Text object { type }` + The text content. - Unconstrained free-form text. + - `type: "output_text"` - - `type: "text"` + The content type. Always `output_text`. - Unconstrained text format. Always `text`. + - `"output_text"` - - `"text"` + - `annotations: optional array of object { file_id, filename, index, type } or array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` - - `Grammar object { definition, syntax, type }` + Citations associated with the text content. - A grammar defined by the user. + - `array of object { file_id, filename, index, type }` - - `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 citation type. Always `file_citation`. - - `"grammar"` + - `"file_citation"` - - `Namespace object { description, name, tools, type }` + - `array of object { end_index, start_index, title, 2 more }` - Groups function/custom tools under a shared namespace. + - `end_index: number` - - `description: string` + The index of the last character of the citation in the message. - A description of the namespace shown to the model. + - `start_index: number` - - `name: string` + The index of the first character of the citation in the message. - The namespace name used in tool calls (for example, `crm`). + - `title: string` - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + The title of the cited resource. - The function/custom tools available inside this namespace. + - `type: "url_citation"` - - `Function object { name, type, allowed_callers, 5 more }` + The citation type. Always `url_citation`. - - `name: string` + - `"url_citation"` - - `type: "function"` + - `url: string` - - `"function"` + The URL of the cited resource. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `array of object { container_id, end_index, file_id, 3 more }` - The tool invocation context(s). + - `container_id: string` - - `"direct"` + The ID of the container. - - `"programmatic"` + - `end_index: number` - - `defer_loading: optional boolean` + The index of the last character of the citation in the message. - Whether this function should be deferred and discovered via tool search. + - `file_id: string` - - `description: optional string` + The ID of the container file. - - `output_schema: optional map[unknown]` + - `filename: string` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + The filename of the container file cited. - - `parameters: optional unknown` + - `start_index: number` - - `strict: optional boolean` + The index of the first character of the citation in the 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. + - `type: "container_file_citation"` - - `Custom object { name, type, allowed_callers, 3 more }` + The citation type. Always `container_file_citation`. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `"container_file_citation"` - - `name: string` + - `type: "multi_agent_call_output"` - The name of the custom tool, used to identify it in tool calls. + The item type. Always `multi_agent_call_output`. - - `type: "custom"` + - `"multi_agent_call_output"` - The type of the custom tool. Always `custom`. + - `id: optional string` - - `"custom"` + The unique ID of this multi-agent call output. - - `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` + - `ToolSearchCall object { arguments, type, id, 4 more }` - Whether this tool should be deferred and discovered via tool search. + - `arguments: unknown` - - `description: optional string` + The arguments supplied to the tool search call. - Optional description of the custom tool, used to provide more context. + - `type: "tool_search_call"` - - `format: optional object { type } or object { definition, syntax, type }` + The item type. Always `tool_search_call`. - The input format for the custom tool. Default is unconstrained text. + - `"tool_search_call"` - - `Text object { type }` + - `id: optional string` - Unconstrained free-form text. + The unique ID of this tool search call. - - `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. + - `call_id: optional string` - - `definition: string` + The unique ID of the tool search call generated by the model. - The grammar definition. + - `execution: optional "server" or "client"` - - `syntax: "lark" or "regex"` + Whether tool search was executed by the server or by the client. - The syntax of the grammar definition. One of `lark` or `regex`. + - `"server"` - - `"lark"` + - `"client"` - - `"regex"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `type: "grammar"` + The status of the tool search call. - Grammar format. Always `grammar`. + - `"in_progress"` - - `"grammar"` + - `"completed"` - - `type: "namespace"` + - `"incomplete"` - The type of the tool. Always `namespace`. + - `ToolSearchOutput object { tools, type, id, 4 more }` - - `"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` - - `ToolSearch object { type, description, execution, parameters }` + The loaded tool definitions returned by the tool search output. - Hosted or BYOT tool search configuration for deferred tools. + - `Function object { name, parameters, strict, 5 more }` - - `type: "tool_search"` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - The type of the tool. Always `tool_search`. + - `name: string` - - `"tool_search"` + The name of the function to call. - - `description: optional string` + - `parameters: map[unknown]` - Description shown to the model for a client-executed tool search tool. + A JSON schema object describing the parameters of the function. - - `execution: optional "server" or "client"` + - `strict: boolean` - Whether tool search is executed by the server or by the client. + Whether strict parameter validation is enforced for this function tool. - - `"server"` + - `type: "function"` - - `"client"` + The type of the function tool. Always `function`. - - `parameters: optional unknown` + - `"function"` - Parameter schema for a client-executed tool search tool. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + The tool invocation context(s). - 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). + - `"direct"` - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `"programmatic"` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `defer_loading: optional boolean` - - `"web_search_preview"` + Whether this function is deferred and loaded via tool search. - - `"web_search_preview_2025_03_11"` + - `description: optional string` - - `search_content_types: optional array of "text" or "image"` + A description of the function. Used by the model to determine whether or not to call the function. - - `"text"` + - `output_schema: optional map[unknown]` - - `"image"` + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `search_context_size: optional "low" or "medium" or "high"` + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + 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"` - - `"medium"` + The type of the file search tool. Always `file_search`. - - `"high"` + - `"file_search"` - - `user_location: optional object { type, city, country, 2 more }` + - `vector_store_ids: array of string` - The user's location. + The IDs of the vector stores to search. - - `type: "approximate"` + - `filters: optional object { key, type, value } or object { filters, type }` - The type of location approximation. Always `approximate`. + A filter to apply. - - `"approximate"` + - `ComparisonFilter object { key, type, value }` - - `city: optional string` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - Free text input for the city of the user, e.g. `San Francisco`. + - `key: string` - - `country: optional string` + The key to compare against the value. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `type: "eq" or "ne" or "gt" or 5 more` - - `region: optional string` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - Free text input for the region of the user, e.g. `California`. + - `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 - - `timezone: optional string` + - `"eq"` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `"ne"` - - `ApplyPatch object { type, allowed_callers }` + - `"gt"` - Allows the assistant to create, delete, or update files using unified diffs. + - `"gte"` - - `type: "apply_patch"` + - `"lt"` - The type of the tool. Always `apply_patch`. + - `"lte"` - - `"apply_patch"` + - `"in"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"nin"` - The tool invocation context(s). + - `value: string or number or boolean or array of string or number` - - `"direct"` + The value to compare against the attribute key; supports string, number, or boolean types. - - `"programmatic"` + - `string` - - `type: "additional_tools"` + - `number` - The item type. Always `additional_tools`. + - `boolean` - - `"additional_tools"` + - `array of string or number` - - `id: optional string` + - `string` - The unique ID of this additional tools item. + - `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`. - - `Reasoning object { id, summary, type, 4 more }` + - `ComparisonFilter object { key, type, value }` - 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](https://platform.openai.com/docs/guides/conversation-state). + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `id: string` + - `key: string` - The unique identifier of the reasoning content. + The key to compare against the value. - - `summary: array of object { text, type }` + - `type: "eq" or "ne" or "gt" or 5 more` - Reasoning summary content. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `text: 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 - A summary of the reasoning output from the model so far. + - `"eq"` - - `type: "summary_text"` + - `"ne"` - The type of the object. Always `summary_text`. + - `"gt"` - - `"summary_text"` + - `"gte"` - - `type: "reasoning"` + - `"lt"` - The type of the object. Always `reasoning`. + - `"lte"` - - `"reasoning"` + - `"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` - - `content: optional array of object { text, type }` + - `number` - Reasoning text content. + - `boolean` - - `text: string` + - `array of string or number` - The reasoning text from the model. + - `string` - - `type: "reasoning_text"` + - `number` - The type of the reasoning text. Always `reasoning_text`. + - `unknown` - - `"reasoning_text"` + - `type: "and" or "or"` - - `encrypted_content: optional string` + Type of operation: `and` or `or`. - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `"and"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"or"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `max_num_results: optional number` - - `"in_progress"` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `"completed"` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `"incomplete"` + Ranking options for search. - - `Compaction object { encrypted_content, type, id, agent }` + - `hybrid_search: optional object { embedding_weight, text_weight }` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `encrypted_content: string` + - `embedding_weight: number` - The encrypted content of the compaction summary. + The weight of the embedding in the reciprocal ranking fusion. - - `type: "compaction"` + - `text_weight: number` - The type of the item. Always `compaction`. + The weight of the text in the reciprocal ranking fusion. - - `"compaction"` + - `ranker: optional "auto" or "default-2024-11-15"` - - `id: optional string` + The ranker to use for the file search. - The ID of the compaction item. + - `"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 }` - - `ImageGenerationCall object { id, result, status, 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 generation request made by the model. + - `type: "computer"` - - `id: string` + The type of the computer tool. Always `computer`. - The unique ID of the image generation call. + - `"computer"` - - `result: string` + - `ComputerUsePreview object { display_height, display_width, environment, type }` - The generated image encoded in base64. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `status: "in_progress" or "completed" or "generating" or "failed"` + - `display_height: number` - The status of the image generation call. + The height of the computer display. - - `"in_progress"` + - `display_width: number` - - `"completed"` + The width of the computer display. - - `"generating"` + - `environment: "windows" or "mac" or "linux" or 2 more` - - `"failed"` + The type of computer environment to control. - - `type: "image_generation_call"` + - `"windows"` - The type of the image generation call. Always `image_generation_call`. + - `"mac"` - - `"image_generation_call"` + - `"linux"` - - `agent: optional object { agent_name }` + - `"ubuntu"` - The agent that produced this item. + - `"browser"` - - `agent_name: string` + - `type: "computer_use_preview"` - The canonical name of the agent that produced this item. + The type of the computer use tool. Always `computer_use_preview`. - - `CodeInterpreterCall object { id, code, container_id, 4 more }` + - `"computer_use_preview"` - A tool call to run code. + - `WebSearch object { type, filters, search_context_size, user_location }` - - `id: string` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - The unique ID of the code interpreter tool call. + - `type: "web_search" or "web_search_2025_08_26"` - - `code: string` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - The code to run, or null if not available. + - `"web_search"` - - `container_id: string` + - `"web_search_2025_08_26"` - The ID of the container used to run the code. + - `filters: optional object { allowed_domains }` - - `outputs: array of object { logs, type } or object { type, url }` + Filters for the search. - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `allowed_domains: optional array of string` - - `Logs object { logs, type }` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - The logs output from the code interpreter. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `logs: string` + - `search_context_size: optional "low" or "medium" or "high"` - The logs output from the code interpreter. + 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: "logs"` + - `"low"` - The type of the output. Always `logs`. + - `"medium"` - - `"logs"` + - `"high"` - - `Image object { type, url }` + - `user_location: optional object { city, country, region, 2 more }` - The image output from the code interpreter. + The approximate location of the user. - - `type: "image"` + - `city: optional string` - The type of the output. Always `image`. + Free text input for the city of the user, e.g. `San Francisco`. - - `"image"` + - `country: optional string` - - `url: 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 image output from the code interpreter. + - `region: optional string` - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + Free text input for the region of the user, e.g. `California`. - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `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`. - - `"interpreting"` + - `"approximate"` - - `"failed"` + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `type: "code_interpreter_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 code interpreter tool call. Always `code_interpreter_call`. + - `server_label: string` - - `"code_interpreter_call"` + A label for this MCP server, used to identify it in tool calls. - - `agent: optional object { agent_name }` + - `type: "mcp"` - The agent that produced this item. + 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"` - - `LocalShellCall object { id, action, call_id, 3 more }` + The tool invocation context(s). - A tool call to run a command on the local shell. + - `"direct"` - - `id: string` + - `"programmatic"` - The unique ID of the local shell call. + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `action: object { command, env, type, 3 more }` + List of allowed tool names or a filter object. - Execute a shell command on the server. + - `McpAllowedTools = array of string` - - `command: array of string` + A string array of allowed tool names - The command to run. + - `McpToolFilter object { read_only, tool_names }` - - `env: map[string]` + A filter object to specify which tools are allowed. - Environment variables to set for the command. + - `read_only: optional boolean` - - `type: "exec"` + 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 local shell action. Always `exec`. + - `tool_names: optional array of string` - - `"exec"` + List of allowed tool names. - - `timeout_ms: optional number` + - `authorization: optional string` - Optional timeout in milliseconds for the command. + 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. - - `user: optional string` + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - Optional user to run the command as. + 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). - - `working_directory: optional string` + Currently supported `connector_id` values are: - Optional working directory to run the command in. + - 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` - - `call_id: string` + - `"connector_dropbox"` - The unique ID of the local shell tool call generated by the model. + - `"connector_gmail"` - - `status: "in_progress" or "completed" or "incomplete"` + - `"connector_googlecalendar"` - The status of the local shell call. + - `"connector_googledrive"` - - `"in_progress"` + - `"connector_microsoftteams"` - - `"completed"` + - `"connector_outlookcalendar"` - - `"incomplete"` + - `"connector_outlookemail"` - - `type: "local_shell_call"` + - `"connector_sharepoint"` - The type of the local shell call. Always `local_shell_call`. + - `defer_loading: optional boolean` - - `"local_shell_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. - - `LocalShellCallOutput object { id, output, type, 2 more }` + - `McpToolApprovalFilter object { always, never }` - The output of a local shell 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. - - `id: string` + - `always: optional object { read_only, tool_names }` - The unique ID of the local shell tool call generated by the model. + A filter object to specify which tools are allowed. - - `output: string` + - `read_only: optional boolean` - A JSON string of the output of the local shell 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: "local_shell_call_output"` + - `tool_names: optional array of string` - The type of the local shell tool call output. Always `local_shell_call_output`. + List of allowed tool names. - - `"local_shell_call_output"` + - `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` - - `status: optional "in_progress" or "completed" or "incomplete"` + List of allowed tool names. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `McpToolApprovalSetting = "always" or "never"` - - `"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. - - `"completed"` + - `"always"` - - `"incomplete"` + - `"never"` - - `ShellCall object { action, call_id, type, 5 more }` + - `server_description: optional string` - A tool representing a request to execute one or more shell commands. + Optional description of the MCP server, used to provide more context. - - `action: object { commands, max_output_length, timeout_ms }` + - `server_url: optional string` - The shell commands and limits that describe how to run the tool call. + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `commands: array of string` + - `tunnel_id: optional string` - Ordered shell commands for the execution environment to run. + 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. - - `max_output_length: optional number` + - `CodeInterpreter object { container, type, allowed_callers }` - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + A tool that runs Python code to help generate a response to a prompt. - - `timeout_ms: optional number` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - Maximum wall-clock time in milliseconds to allow the shell commands 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. - - `call_id: string` + - `string` - The unique ID of the shell tool call generated by the model. + The container ID. - - `type: "shell_call"` + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - The type of the item. Always `shell_call`. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `"shell_call"` + - `type: "auto"` - - `id: optional string` + Always `auto`. - The unique ID of the shell 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` - - `environment: optional BetaLocalEnvironment or BetaContainerReference` + A list of allowed domains when type is `allowlist`. - The environment to execute the shell commands in. + - `type: "allowlist"` - - `BetaLocalEnvironment object { type, skills }` + Allow outbound network access only to specified domains. Always `allowlist`. - - `BetaContainerReference object { container_id, type }` + - `"allowlist"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + Optional domain-scoped secrets for allowlisted domains. - - `"in_progress"` + - `domain: string` - - `"completed"` + The domain associated with the secret. - - `"incomplete"` + - `name: string` - - `ShellCallOutput object { call_id, output, type, 5 more }` + The name of the secret to inject for the domain. - The streamed output items emitted by a shell tool call. + - `value: string` - - `call_id: string` + The secret value to inject for the domain. - The unique ID of the shell tool call generated by the model. + - `type: "code_interpreter"` - - `output: array of BetaResponseFunctionShellCallOutputContent` + The type of the code interpreter tool. Always `code_interpreter`. - Captured chunks of stdout and stderr output, along with their associated outcomes. + - `"code_interpreter"` - - `outcome: object { type } or object { exit_code, type }` + - `allowed_callers: optional array of "direct" or "programmatic"` - The exit or timeout outcome associated with this shell call. + The tool invocation context(s). - - `Timeout object { type }` + - `"direct"` - Indicates that the shell call exceeded its configured time limit. + - `"programmatic"` - - `type: "timeout"` + - `ProgrammaticToolCalling object { type }` - The outcome type. Always `timeout`. + - `type: "programmatic_tool_calling"` - - `"timeout"` + The type of the tool. Always `programmatic_tool_calling`. - - `Exit object { exit_code, type }` + - `"programmatic_tool_calling"` - Indicates that the shell commands finished and returned an exit code. + - `ImageGeneration object { type, action, background, 9 more }` - - `exit_code: number` + A tool that generates images using the GPT image models. - The exit code returned by the shell process. + - `type: "image_generation"` - - `type: "exit"` + The type of the image generation tool. Always `image_generation`. - The outcome type. Always `exit`. + - `"image_generation"` - - `"exit"` + - `action: optional "generate" or "edit" or "auto"` - - `stderr: string` + Whether to generate a new image or edit an existing image. Default: `auto`. - Captured stderr output for the shell call. + - `"generate"` - - `stdout: string` + - `"edit"` - Captured stdout output for the shell call. + - `"auto"` - - `type: "shell_call_output"` + - `background: optional "transparent" or "opaque" or "auto"` - The type of the item. Always `shell_call_output`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - - `"shell_call_output"` + - `"transparent"` - - `id: optional string` + - `"opaque"` - The unique ID of the shell tool call output. Populated when this item is returned via API. + - `"auto"` - - `agent: optional object { agent_name }` + - `input_fidelity: optional "high" or "low"` - 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`. - - `agent_name: string` + - `"high"` - The canonical name of the agent that produced this item. + - `"low"` - - `caller: optional object { type } or object { caller_id, type }` + - `input_image_mask: optional object { file_id, image_url }` - The execution context that produced this tool call. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `Direct object { type }` + - `file_id: optional string` - - `type: "direct"` + File ID for the mask image. - The caller type. Always `direct`. + - `image_url: optional string` - - `"direct"` + Base64-encoded mask image. - - `Program object { caller_id, type }` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `caller_id: string` + The image generation model to use. Default: `gpt-image-1`. - The call ID of the program item that produced this tool call. + - `string` - - `type: "program"` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - The caller type. Always `program`. + The image generation model to use. Default: `gpt-image-1`. - - `"program"` + - `"gpt-image-1"` - - `max_output_length: optional number` + - `"gpt-image-1-mini"` - The maximum number of UTF-8 characters captured for this shell call's combined output. + - `"gpt-image-1.5"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `moderation: optional "auto" or "low"` - The status of the shell call output. + Moderation level for the generated image. Default: `auto`. - - `"in_progress"` + - `"auto"` - - `"completed"` + - `"low"` - - `"incomplete"` + - `output_compression: optional number` - - `ApplyPatchCall object { call_id, operation, status, 4 more }` + Compression level for the output image. Default: 100. - A tool call representing a request to create, delete, or update files using diff patches. + - `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 apply patch tool call generated by the model. + - `"png"` - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + - `"webp"` - The specific create, delete, or update instruction for the apply_patch tool call. + - `"jpeg"` - - `CreateFile object { diff, path, type }` + - `partial_images: optional number` - Instruction for creating a new file via the apply_patch tool. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `diff: string` + - `quality: optional "low" or "medium" or "high" or "auto"` - Unified diff content to apply when creating the file. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `path: string` + - `"low"` - Path of the file to create relative to the workspace root. + - `"medium"` - - `type: "create_file"` + - `"high"` - The operation type. Always `create_file`. + - `"auto"` - - `"create_file"` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `DeleteFile object { path, 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`. - Instruction for deleting an existing file via the apply_patch tool. + - `string` - - `path: string` + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - Path of the file to delete relative to the workspace root. + 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: "delete_file"` + - `"1024x1024"` - The operation type. Always `delete_file`. + - `"1024x1536"` - - `"delete_file"` + - `"1536x1024"` - - `UpdateFile object { diff, path, type }` + - `"auto"` - Instruction for updating an existing file via the apply_patch tool. + - `LocalShell object { type }` - - `diff: string` + A tool that allows the model to execute shell commands in a local environment. - Unified diff content to apply to the existing file. + - `type: "local_shell"` - - `path: string` + The type of the local shell tool. Always `local_shell`. - Path of the file to update relative to the workspace root. + - `"local_shell"` - - `type: "update_file"` + - `Shell object { type, allowed_callers, environment }` - The operation type. Always `update_file`. + A tool that allows the model to execute shell commands. - - `"update_file"` + - `type: "shell"` - - `status: "in_progress" or "completed"` + The type of the shell tool. Always `shell`. - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `"shell"` - - `"in_progress"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"completed"` + The tool invocation context(s). - - `type: "apply_patch_call"` + - `"direct"` - The type of the item. Always `apply_patch_call`. + - `"programmatic"` - - `"apply_patch_call"` + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - `id: optional string` + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `type: "container_auto"` - - `agent: optional object { agent_name }` + Automatically creates a container for this request - The agent that produced this item. + - `"container_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 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`. + - `skills: optional array of BetaSkillReference or BetaInlineSkill` - - `"program"` + An optional list of skills referenced by id or inline data. - - `ApplyPatchCallOutput object { call_id, status, type, 4 more }` + - `BetaSkillReference object { skill_id, type, version }` - The streamed output emitted by an apply patch tool call. + - `skill_id: string` - - `call_id: string` + The ID of the referenced skill. - The unique ID of the apply patch tool call generated by the model. + - `type: "skill_reference"` - - `status: "completed" or "failed"` + References a skill created with the /v1/skills endpoint. - The status of the apply patch tool call output. One of `completed` or `failed`. + - `"skill_reference"` - - `"completed"` + - `version: optional string` - - `"failed"` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `type: "apply_patch_call_output"` + - `BetaInlineSkill object { description, name, source, type }` - The type of the item. Always `apply_patch_call_output`. + - `description: string` - - `"apply_patch_call_output"` + The description of the skill. - - `id: optional string` + - `name: string` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + 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. - - `caller: optional object { type } or object { caller_id, type }` + - `media_type: "application/zip"` - The execution context that produced this tool call. + The media type of the inline skill payload. Must be `application/zip`. - - `Direct object { type }` + - `"application/zip"` - - `type: "direct"` + - `type: "base64"` - The caller type. Always `direct`. + The type of the inline skill source. Must be `base64`. - - `"direct"` + - `"base64"` - - `Program object { caller_id, type }` + - `type: "inline"` - - `caller_id: string` + Defines an inline skill for this request. - The call ID of the program item that produced this tool call. + - `"inline"` - - `type: "program"` + - `BetaLocalEnvironment object { type, skills }` - The caller type. Always `program`. + - `type: "local"` - - `"program"` + Use a local computer environment. - - `output: optional string` + - `"local"` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + - `skills: optional array of BetaLocalSkill` - - `McpListTools object { id, server_label, tools, 3 more }` + An optional list of skills. - A list of tools available on an MCP server. + - `description: string` - - `id: string` + The description of the skill. - The unique ID of the list. + - `name: string` - - `server_label: string` + The name of the skill. - The label of the MCP server. + - `path: string` - - `tools: array of object { input_schema, name, annotations, description }` + The path to the directory containing the skill. - The tools available on the server. + - `BetaContainerReference object { container_id, type }` - - `input_schema: unknown` + - `container_id: string` - The JSON schema describing the tool's input. + The ID of the referenced container. - - `name: string` + - `type: "container_reference"` - The name of the tool. + References a container created with the /v1/containers endpoint - - `annotations: optional unknown` + - `"container_reference"` - Additional annotations about the tool. + - `Custom object { name, type, allowed_callers, 3 more }` - - `description: optional string` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - The description of the tool. + - `name: string` - - `type: "mcp_list_tools"` + The name of the custom tool, used to identify it in tool calls. - The type of the item. Always `mcp_list_tools`. + - `type: "custom"` - - `"mcp_list_tools"` + 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"` - - `error: optional string` + - `"programmatic"` - Error message if the server could not list tools. + - `defer_loading: optional boolean` - - `McpApprovalRequest object { id, arguments, name, 3 more }` + Whether this tool should be deferred and discovered via tool search. - A request for human approval of a tool invocation. + - `description: optional string` - - `id: string` + Optional description of the custom tool, used to provide more context. - The unique ID of the approval request. + - `format: optional object { type } or object { definition, syntax, type }` - - `arguments: string` + The input format for the custom tool. Default is unconstrained text. - A JSON string of arguments for the tool. + - `Text object { type }` - - `name: string` + Unconstrained free-form text. - The name of the tool to run. + - `type: "text"` - - `server_label: string` + Unconstrained text format. Always `text`. - The label of the MCP server making the request. + - `"text"` - - `type: "mcp_approval_request"` + - `Grammar object { definition, syntax, type }` - The type of the item. Always `mcp_approval_request`. + A grammar defined by the user. - - `"mcp_approval_request"` + - `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"` - - `McpApprovalResponse object { approval_request_id, approve, type, 3 more }` + - `"regex"` - A response to an MCP approval request. + - `type: "grammar"` - - `approval_request_id: string` + Grammar format. Always `grammar`. - The ID of the approval request being answered. + - `"grammar"` - - `approve: boolean` + - `Namespace object { description, name, tools, type }` - Whether the request was approved. + Groups function/custom tools under a shared namespace. - - `type: "mcp_approval_response"` + - `description: string` - The type of the item. Always `mcp_approval_response`. + A description of the namespace shown to the model. - - `"mcp_approval_response"` + - `name: string` - - `id: optional string` + The namespace name used in tool calls (for example, `crm`). - The unique ID of the approval response + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - - `agent: optional object { agent_name }` + The function/custom tools available inside this namespace. - The agent that produced this item. + - `Function object { name, type, allowed_callers, 5 more }` - - `agent_name: string` + - `name: string` - The canonical name of the agent that produced this item. + - `type: "function"` - - `reason: optional string` + - `"function"` - Optional reason for the decision. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `McpCall object { id, arguments, name, 7 more }` + The tool invocation context(s). - An invocation of a tool on an MCP server. + - `"direct"` - - `id: string` + - `"programmatic"` - The unique ID of the tool call. + - `defer_loading: optional boolean` - - `arguments: string` + Whether this function should be deferred and discovered via tool search. - A JSON string of the arguments passed to the tool. + - `description: optional string` - - `name: string` + - `output_schema: optional map[unknown]` - The name of the tool that was run. + 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 running the tool. + - `strict: optional boolean` - - `type: "mcp_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. - The type of the item. Always `mcp_call`. + - `Custom object { name, type, allowed_callers, 3 more }` - - `"mcp_call"` + 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`. - - `approval_request_id: optional string` + - `"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. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `error: optional string` + The tool invocation context(s). - The error from the tool call, if any. + - `"direct"` - - `output: optional string` + - `"programmatic"` - The output from the tool call. + - `defer_loading: optional boolean` - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + Whether this tool should be deferred and discovered via tool search. - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `description: optional string` - - `"in_progress"` + Optional description of the custom tool, used to provide more context. - - `"completed"` + - `format: optional object { type } or object { definition, syntax, type }` - - `"incomplete"` + The input format for the custom tool. Default is unconstrained text. - - `"calling"` + - `Text object { type }` - - `"failed"` + Unconstrained free-form text. - - `CustomToolCallOutput object { call_id, output, type, 3 more }` + - `type: "text"` - The output of a custom tool call from your code, being sent back to the model. + Unconstrained text format. Always `text`. - - `call_id: string` + - `"text"` - The call ID, used to map this custom tool call output to a custom tool call. + - `Grammar object { definition, syntax, type }` - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + A grammar defined by the user. - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `definition: string` - - `StringOutput = string` + The grammar definition. - A string of the output of the custom tool call. + - `syntax: "lark" or "regex"` - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + The syntax of the grammar definition. One of `lark` or `regex`. - Text, image, or file output of the custom tool call. + - `"lark"` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `"regex"` - A text input to the model. + - `type: "grammar"` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + Grammar format. Always `grammar`. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `"grammar"` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `type: "namespace"` - A file input to the model. + The type of the tool. Always `namespace`. - - `type: "custom_tool_call_output"` + - `"namespace"` - The type of the custom tool call output. Always `custom_tool_call_output`. + - `ToolSearch object { type, description, execution, parameters }` - - `"custom_tool_call_output"` + Hosted or BYOT tool search configuration for deferred tools. - - `id: optional string` + - `type: "tool_search"` - The unique ID of the custom tool call output in the OpenAI platform. + 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"` - - `caller: optional object { type } or object { caller_id, type }` + Whether tool search is executed by the server or by the client. - The execution context that produced this tool call. + - `"server"` - - `Direct object { type }` + - `"client"` - - `type: "direct"` + - `parameters: optional unknown` - The caller type. Always `direct`. + Parameter schema for a client-executed tool search tool. - - `"direct"` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - - `Program object { caller_id, 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). - - `caller_id: string` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - The call ID of the program item that produced this tool call. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `type: "program"` + - `"web_search_preview"` - The caller type. Always `program`. + - `"web_search_preview_2025_03_11"` - - `"program"` + - `search_content_types: optional array of "text" or "image"` - - `CustomToolCall object { call_id, input, name, 5 more }` + - `"text"` - A call to a custom tool created by the model. + - `"image"` - - `call_id: string` + - `search_context_size: optional "low" or "medium" or "high"` - An identifier used to map this custom tool call to a 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. - - `input: string` + - `"low"` - The input for the custom tool call generated by the model. + - `"medium"` - - `name: string` + - `"high"` - The name of the custom tool being called. + - `user_location: optional object { type, city, country, 2 more }` - - `type: "custom_tool_call"` + The user's location. - The type of the custom tool call. Always `custom_tool_call`. + - `type: "approximate"` - - `"custom_tool_call"` + The type of location approximation. Always `approximate`. - - `id: optional string` + - `"approximate"` - The unique ID of the custom tool call in the OpenAI platform. + - `city: optional string` - - `agent: optional object { agent_name }` + Free text input for the city of the user, e.g. `San Francisco`. - The agent that produced this item. + - `country: optional string` - - `agent_name: string` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The canonical name of the agent that produced this item. + - `region: optional string` - - `caller: optional object { type } or object { caller_id, type }` + Free text input for the region of the user, e.g. `California`. - The execution context that produced this tool call. + - `timezone: optional string` - - `Direct object { type }` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `type: "direct"` + - `ApplyPatch object { type, allowed_callers }` - - `"direct"` + Allows the assistant to create, delete, or update files using unified diffs. - - `Program object { caller_id, type }` + - `type: "apply_patch"` - - `caller_id: string` + The type of the tool. Always `apply_patch`. - The call ID of the program item that produced this tool call. + - `"apply_patch"` - - `type: "program"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"program"` + The tool invocation context(s). - - `namespace: optional string` + - `"direct"` - The namespace of the custom tool being called. + - `"programmatic"` - - `CompactionTrigger object { type, agent }` + - `type: "tool_search_output"` - Compacts the current context. Must be the final input item. + The item type. Always `tool_search_output`. - - `type: "compaction_trigger"` + - `"tool_search_output"` - The type of the item. Always `compaction_trigger`. + - `id: optional string` - - `"compaction_trigger"` + The unique ID of this tool search output. - `agent: optional object { agent_name }` @@ -93251,1028 +92167,1038 @@ 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. + - `call_id: optional string` - - `agent: optional object { agent_name }` + The unique ID of the tool search call generated by the model. - The agent that produced this item. + - `execution: optional "server" or "client"` - - `agent_name: string` + Whether tool search was executed by the server or by the client. - The canonical name of the agent that produced this item. + - `"server"` - - `type: optional "item_reference"` + - `"client"` - The type of item to reference. Always `item_reference`. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"item_reference"` + The status of the tool search output. - - `Program object { id, call_id, code, 3 more }` + - `"in_progress"` - - `id: string` + - `"completed"` - The unique ID of this program item. + - `"incomplete"` - - `call_id: string` + - `AdditionalTools object { role, tools, type, 2 more }` - The stable call ID of the program item. + - `role: "developer"` - - `code: string` + The role that provided the additional tools. Only `developer` is supported. - The JavaScript source executed by programmatic tool calling. + - `"developer"` - - `fingerprint: 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` - Opaque program replay fingerprint that must be round-tripped. + A list of additional tools made available at this item. - - `type: "program"` + - `Function object { name, parameters, strict, 5 more }` - The item type. Always `program`. + 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). - - `"program"` + - `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` - - `ProgramOutput object { id, call_id, result, 3 more }` + Whether strict parameter validation is enforced for this function tool. - - `id: string` + - `type: "function"` - The unique ID of this program output item. + The type of the function tool. Always `function`. - - `call_id: string` + - `"function"` - 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 function is deferred and loaded via tool search. - - `"incomplete"` + - `description: optional string` - - `type: "program_output"` + A description of the function. Used by the model to determine whether or not to call the function. - The item type. Always `program_output`. + - `output_schema: optional map[unknown]` - - `"program_output"` + 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`. - - `metadata: map[string]` + - `"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. + - `vector_store_ids: array of string` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The IDs of the vector stores to search. - - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` + - `filters: optional object { key, type, value } or object { filters, 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](https://platform.openai.com/docs/models) - to browse and compare available models. + A filter to apply. - - `"gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more` + - `ComparisonFilter object { key, type, value }` - 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](https://platform.openai.com/docs/models) - to browse and compare available models. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `"gpt-5.6-sol"` + - `key: string` - - `"gpt-5.6-terra"` + The key to compare against the value. - - `"gpt-5.6-luna"` + - `type: "eq" or "ne" or "gt" or 5 more` - - `"gpt-5.4"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `"gpt-5.4-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-5.4-nano"` + - `"eq"` - - `"gpt-5.4-mini-2026-03-17"` + - `"ne"` - - `"gpt-5.4-nano-2026-03-17"` + - `"gt"` - - `"gpt-5.3-chat-latest"` + - `"gte"` - - `"gpt-5.2"` + - `"lt"` - - `"gpt-5.2-2025-12-11"` + - `"lte"` - - `"gpt-5.2-chat-latest"` + - `"in"` - - `"gpt-5.2-pro"` + - `"nin"` - - `"gpt-5.2-pro-2025-12-11"` + - `value: string or number or boolean or array of string or number` - - `"gpt-5.1"` + The value to compare against the attribute key; supports string, number, or boolean types. - - `"gpt-5.1-2025-11-13"` + - `string` - - `"gpt-5.1-codex"` + - `number` - - `"gpt-5.1-mini"` + - `boolean` - - `"gpt-5.1-chat-latest"` + - `array of string or number` - - `"gpt-5"` + - `string` - - `"gpt-5-mini"` + - `number` - - `"gpt-5-nano"` + - `CompoundFilter object { filters, type }` - - `"gpt-5-2025-08-07"` + Combine multiple filters using `and` or `or`. - - `"gpt-5-mini-2025-08-07"` + - `filters: array of object { key, type, value } or unknown` - - `"gpt-5-nano-2025-08-07"` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `"gpt-5-chat-latest"` + - `ComparisonFilter object { key, type, value }` - - `"gpt-4.1"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `"gpt-4.1-mini"` + - `key: string` - - `"gpt-4.1-nano"` + The key to compare against the value. - - `"gpt-4.1-2025-04-14"` + - `type: "eq" or "ne" or "gt" or 5 more` - - `"gpt-4.1-mini-2025-04-14"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `"gpt-4.1-nano-2025-04-14"` + - `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 - - `"o4-mini"` + - `"eq"` - - `"o4-mini-2025-04-16"` + - `"ne"` - - `"o3"` + - `"gt"` - - `"o3-2025-04-16"` + - `"gte"` - - `"o3-mini"` + - `"lt"` - - `"o3-mini-2025-01-31"` + - `"lte"` - - `"o1"` + - `"in"` - - `"o1-2024-12-17"` + - `"nin"` - - `"o1-preview"` + - `value: string or number or boolean or array of string or number` - - `"o1-preview-2024-09-12"` + The value to compare against the attribute key; supports string, number, or boolean types. - - `"o1-mini"` + - `string` - - `"o1-mini-2024-09-12"` + - `number` - - `"gpt-4o"` + - `boolean` - - `"gpt-4o-2024-11-20"` + - `array of string or number` - - `"gpt-4o-2024-08-06"` + - `string` - - `"gpt-4o-2024-05-13"` + - `number` - - `"gpt-4o-audio-preview"` + - `unknown` - - `"gpt-4o-audio-preview-2024-10-01"` + - `type: "and" or "or"` - - `"gpt-4o-audio-preview-2024-12-17"` + Type of operation: `and` or `or`. - - `"gpt-4o-audio-preview-2025-06-03"` + - `"and"` - - `"gpt-4o-mini-audio-preview"` + - `"or"` - - `"gpt-4o-mini-audio-preview-2024-12-17"` + - `max_num_results: optional number` - - `"gpt-4o-search-preview"` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `"gpt-4o-mini-search-preview"` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `"gpt-4o-search-preview-2025-03-11"` + Ranking options for search. - - `"gpt-4o-mini-search-preview-2025-03-11"` + - `hybrid_search: optional object { embedding_weight, text_weight }` - - `"chatgpt-4o-latest"` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `"codex-mini-latest"` + - `embedding_weight: number` - - `"gpt-4o-mini"` + The weight of the embedding in the reciprocal ranking fusion. - - `"gpt-4o-mini-2024-07-18"` + - `text_weight: number` - - `"gpt-4-turbo"` + The weight of the text in the reciprocal ranking fusion. - - `"gpt-4-turbo-2024-04-09"` + - `ranker: optional "auto" or "default-2024-11-15"` - - `"gpt-4-0125-preview"` + The ranker to use for the file search. - - `"gpt-4-turbo-preview"` + - `"auto"` - - `"gpt-4-1106-preview"` + - `"default-2024-11-15"` - - `"gpt-4-vision-preview"` + - `score_threshold: optional number` - - `"gpt-4"` + 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-0314"` + - `Computer object { type }` - - `"gpt-4-0613"` + 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"` + - `type: "computer"` - - `"gpt-4-32k-0314"` + The type of the computer tool. Always `computer`. - - `"gpt-4-32k-0613"` + - `"computer"` - - `"gpt-3.5-turbo"` + - `ComputerUsePreview object { display_height, display_width, environment, type }` - - `"gpt-3.5-turbo-16k"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"gpt-3.5-turbo-0301"` + - `display_height: number` - - `"gpt-3.5-turbo-0613"` + The height of the computer display. - - `"gpt-3.5-turbo-1106"` + - `display_width: number` - - `"gpt-3.5-turbo-0125"` + The width of the computer display. - - `"gpt-3.5-turbo-16k-0613"` + - `environment: "windows" or "mac" or "linux" or 2 more` - - `"o1-pro"` + The type of computer environment to control. - - `"o1-pro-2025-03-19"` + - `"windows"` - - `"o3-pro"` + - `"mac"` - - `"o3-pro-2025-06-10"` + - `"linux"` - - `"o3-deep-research"` + - `"ubuntu"` - - `"o3-deep-research-2025-06-26"` + - `"browser"` - - `"o4-mini-deep-research"` + - `type: "computer_use_preview"` - - `"o4-mini-deep-research-2025-06-26"` + The type of the computer use tool. Always `computer_use_preview`. - - `"computer-use-preview"` + - `"computer_use_preview"` - - `"computer-use-preview-2025-03-11"` + - `WebSearch object { type, filters, search_context_size, user_location }` - - `"gpt-5-codex"` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - - `"gpt-5-pro"` + - `type: "web_search" or "web_search_2025_08_26"` - - `"gpt-5-pro-2025-10-06"` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `"gpt-5.1-codex-max"` + - `"web_search"` - - `string` + - `"web_search_2025_08_26"` - - `object: "response"` + - `filters: optional object { allowed_domains }` - The object type of this resource - always set to `response`. + Filters for the search. - - `"response"` + - `allowed_domains: optional array of string` - - `output: array of BetaResponseOutputItem` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - An array of content items generated by the model. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - 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. + - `search_context_size: optional "low" or "medium" or "high"` - - `BetaResponseOutputMessage object { id, content, role, 4 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. - An output message from the model. + - `"low"` - - `FileSearchCall object { id, queries, status, 3 more }` + - `"medium"` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `"high"` - - `id: string` + - `user_location: optional object { city, country, region, 2 more }` - The unique ID of the file search tool call. + The approximate location of the user. - - `queries: array of string` + - `city: optional string` - The queries used to search for files. + Free text input for the city of the user, e.g. `San Francisco`. - - `status: "in_progress" or "searching" or "completed" or 2 more` + - `country: optional string` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + 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` - - `"searching"` + 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`. - - `"failed"` + - `type: optional "approximate"` - - `type: "file_search_call"` + The type of location approximation. Always `approximate`. - The type of the file search tool call. Always `file_search_call`. + - `"approximate"` - - `"file_search_call"` + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `agent: optional object { agent_name }` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - The agent that produced this item. + - `server_label: string` - - `agent_name: string` + A label for this MCP server, used to identify it in tool calls. - The canonical name of the agent that produced this item. + - `type: "mcp"` - - `results: optional array of object { attributes, file_id, filename, 2 more }` + The type of the MCP tool. Always `mcp`. - The results of the file search tool call. + - `"mcp"` - - `attributes: optional map[string or number or boolean]` + - `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. Keys are strings - with a maximum length of 64 characters. Values are strings with a maximum - length of 512 characters, booleans, or numbers. + The tool invocation context(s). - - `string` + - `"direct"` - - `number` + - `"programmatic"` - - `boolean` + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `file_id: optional string` + List of allowed tool names or a filter object. - The unique ID of the file. + - `McpAllowedTools = array of string` - - `filename: optional string` + A string array of allowed tool names - The name of the file. + - `McpToolFilter object { read_only, tool_names }` - - `score: optional number` + A filter object to specify which tools are allowed. - The relevance score of the file - a value between 0 and 1. + - `read_only: optional boolean` - - `text: 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 text that was retrieved from the file. + - `tool_names: optional array of string` - - `FunctionCall object { arguments, call_id, name, 6 more }` + List of allowed tool names. - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `authorization: optional string` - - `arguments: string` + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - A JSON string of the arguments to pass to the function. + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `call_id: string` + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). - The unique ID of the function tool call generated by the model. + Currently supported `connector_id` values are: - - `name: string` + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - The name of the function to run. + - `"connector_dropbox"` - - `type: "function_call"` + - `"connector_gmail"` - The type of the function tool call. Always `function_call`. + - `"connector_googlecalendar"` - - `"function_call"` + - `"connector_googledrive"` - - `id: optional string` + - `"connector_microsoftteams"` - The unique ID of the function tool call. + - `"connector_outlookcalendar"` - - `agent: optional object { agent_name }` + - `"connector_outlookemail"` - The agent that produced this item. + - `"connector_sharepoint"` - - `agent_name: string` + - `defer_loading: optional boolean` - The canonical name of the agent that produced this item. + Whether this MCP tool is deferred and discovered via tool search. - - `caller: optional object { type } or object { caller_id, type }` + - `headers: optional map[string]` - The execution context that produced this tool call. + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `Direct object { type }` + - `require_approval: optional object { always, never } or "always" or "never"` - - `type: "direct"` + Specify which of the MCP server's tools require approval. - - `"direct"` + - `McpToolApprovalFilter object { always, never }` - - `Program object { caller_id, 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. - - `caller_id: string` + - `always: optional object { read_only, tool_names }` - The call ID of the program item that produced this tool call. + A filter object to specify which tools are allowed. - - `type: "program"` + - `read_only: optional boolean` - - `"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. - - `namespace: optional string` + - `tool_names: optional array of string` - The namespace of the function to run. + List of allowed tool names. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `never: optional object { read_only, tool_names }` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when 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` - - `FunctionCallOutput object { id, call_id, output, 5 more }` + List of allowed tool names. - - `id: string` + - `McpToolApprovalSetting = "always" or "never"` - The unique ID of the function call tool 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. - - `call_id: string` + - `"always"` - The unique ID of the function tool call generated by the model. + - `"never"` - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `server_description: optional string` - The output from the function call generated by your code. - Can be a string or an list of output content. + Optional description of the MCP server, used to provide more context. - - `StringOutput = string` + - `server_url: optional string` - A string of the output of the function call. + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `tunnel_id: optional string` - Text, image, or file output of the function 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. - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `CodeInterpreter object { container, type, allowed_callers }` - A text input to the model. + A tool that runs Python code to help generate a response to a prompt. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + 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. - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `string` - A file input to the model. + The container ID. - - `status: "in_progress" or "completed" or "incomplete"` + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `"in_progress"` + - `type: "auto"` - - `"completed"` + Always `auto`. - - `"incomplete"` + - `"auto"` - - `type: "function_call_output"` + - `file_ids: optional array of string` - The type of the function tool call output. Always `function_call_output`. + An optional list of uploaded files to make available to your code. - - `"function_call_output"` + - `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"` - - `caller: optional object { type } or object { caller_id, type }` + - `"64g"` - The execution context that produced this tool call. + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `Direct object { type }` + Network access policy for the container. - - `type: "direct"` + - `BetaContainerNetworkPolicyDisabled object { type }` - The caller type. Always `direct`. + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `"direct"` + - `type: "code_interpreter"` - - `Program object { caller_id, type }` + The type of the code interpreter tool. Always `code_interpreter`. - - `caller_id: string` + - `"code_interpreter"` - 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). - The caller type. Always `program`. + - `"direct"` - - `"program"` + - `"programmatic"` - - `created_by: optional string` + - `ProgrammaticToolCalling object { type }` - The identifier of the actor that created the item. + - `type: "programmatic_tool_calling"` - - `AgentMessage object { id, author, content, 3 more }` + The type of the tool. Always `programmatic_tool_calling`. - - `id: string` + - `"programmatic_tool_calling"` - The unique ID of the agent message. + - `ImageGeneration object { type, action, background, 9 more }` - - `author: string` + A tool that generates images using the GPT image models. - The sending agent identity. + - `type: "image_generation"` - - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` + The type of the image generation tool. Always `image_generation`. - Encrypted content sent between agents. + - `"image_generation"` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `action: optional "generate" or "edit" or "auto"` - A text input to the model. + Whether to generate a new image or edit an existing image. Default: `auto`. - - `BetaResponseOutputText object { annotations, text, type, logprobs }` + - `"generate"` - A text output from the model. + - `"edit"` - - `Text object { text, type }` + - `"auto"` - A text content. + - `background: optional "transparent" or "opaque" or "auto"` - - `text: string` + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - - `type: "text"` + - `"transparent"` - - `"text"` + - `"opaque"` - - `SummaryText object { text, type }` + - `"auto"` - A summary text from the model. + - `input_fidelity: optional "high" or "low"` - - `text: 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`. - A summary of the reasoning output from the model so far. + - `"high"` - - `type: "summary_text"` + - `"low"` - The type of the object. Always `summary_text`. + - `input_image_mask: optional object { file_id, image_url }` - - `"summary_text"` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `ReasoningText object { text, type }` + - `file_id: optional string` - Reasoning text from the model. + File ID for the mask image. - - `text: string` + - `image_url: optional string` - The reasoning text from the model. + Base64-encoded mask image. - - `type: "reasoning_text"` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - The type of the reasoning text. Always `reasoning_text`. + The image generation model to use. Default: `gpt-image-1`. - - `"reasoning_text"` + - `string` - - `BetaResponseOutputRefusal object { refusal, type }` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - A refusal from the model. + The image generation model to use. Default: `gpt-image-1`. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `"gpt-image-1"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `"gpt-image-1-mini"` - - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` + - `"gpt-image-1.5"` - A screenshot of a computer. + - `moderation: optional "auto" or "low"` - - `detail: "low" or "high" or "auto" or "original"` + Moderation level for the generated image. Default: `auto`. - The detail level of the screenshot 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: string` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - The identifier of an uploaded file that contains the screenshot. + - `"png"` - - `image_url: string` + - `"webp"` - The URL of the screenshot image. + - `"jpeg"` - - `type: "computer_screenshot"` + - `partial_images: optional number` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `"computer_screenshot"` + - `quality: optional "low" or "medium" or "high" or "auto"` - - `prompt_cache_breakpoint: optional object { mode }` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `"low"` - - `mode: "explicit"` + - `"medium"` - The breakpoint mode. Always `explicit`. + - `"high"` - - `"explicit"` + - `"auto"` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - A file input to 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`. - - `EncryptedContent object { encrypted_content, type }` + - `string` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `encrypted_content: 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`. - Opaque encrypted content. + - `"1024x1024"` - - `type: "encrypted_content"` + - `"1024x1536"` - The type of the input item. Always `encrypted_content`. + - `"1536x1024"` - - `"encrypted_content"` + - `"auto"` - - `recipient: string` + - `LocalShell object { type }` - The destination agent identity. + A tool that allows the model to execute shell commands in a local environment. - - `type: "agent_message"` + - `type: "local_shell"` - The type of the item. Always `agent_message`. + The type of the local shell tool. Always `local_shell`. - - `"agent_message"` + - `"local_shell"` - - `agent: optional object { agent_name }` + - `Shell object { type, allowed_callers, environment }` - The agent that produced this item. + A tool that allows the model to execute shell commands. - - `agent_name: string` + - `type: "shell"` - The canonical name of the agent that produced this item. + The type of the shell tool. Always `shell`. - - `MultiAgentCall object { id, action, arguments, 3 more }` + - `"shell"` - - `id: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The unique ID of the multi-agent call item. + The tool invocation context(s). - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `"direct"` - The multi-agent action to execute. + - `"programmatic"` - - `"spawn_agent"` + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - `"interrupt_agent"` + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - - `"list_agents"` + - `BetaLocalEnvironment object { type, skills }` - - `"send_message"` + - `BetaContainerReference object { container_id, type }` - - `"followup_task"` + - `Custom object { name, type, allowed_callers, 3 more }` - - `"wait_agent"` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `arguments: string` + - `name: string` - The JSON string of arguments generated for the action. + The name of the custom tool, used to identify it in tool calls. - - `call_id: string` + - `type: "custom"` - The unique ID linking this call to its output. + The type of the custom tool. Always `custom`. - - `type: "multi_agent_call"` + - `"custom"` - The type of the multi-agent call. Always `multi_agent_call`. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"multi_agent_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 tool should be deferred and discovered via tool search. - - `MultiAgentCallOutput object { id, action, call_id, 3 more }` + - `description: optional string` - - `id: string` + Optional description of the custom tool, used to provide more context. - The unique ID of the multi-agent call output item. + - `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 produced this result. + - `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. - - `call_id: string` + - `definition: string` - The unique ID of the multi-agent call. + The grammar definition. - - `output: array of BetaResponseOutputText` + - `syntax: "lark" or "regex"` - Text output returned by the multi-agent action. + The syntax of the grammar definition. One of `lark` or `regex`. - - `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 }` + - `"lark"` - The annotations of the text output. + - `"regex"` - - `text: string` + - `type: "grammar"` - The text output from the model. + Grammar format. Always `grammar`. - - `type: "output_text"` + - `"grammar"` - The type of the output text. Always `output_text`. + - `Namespace object { description, name, tools, type }` - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + Groups function/custom tools under a shared namespace. - - `type: "multi_agent_call_output"` + - `description: string` - The type of the multi-agent result. Always `multi_agent_call_output`. + A description of the namespace shown to the model. - - `"multi_agent_call_output"` + - `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 }` - - `WebSearchCall object { id, action, status, 2 more }` + - `name: string` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `type: "function"` - - `id: string` + - `"function"` - 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. + - `defer_loading: optional boolean` - - `type: "search"` + Whether this function should be deferred and discovered via tool search. - The action type. + - `description: optional string` - - `"search"` + - `output_schema: optional map[unknown]` - - `queries: 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 search queries. + - `parameters: optional unknown` - - `query: optional string` + - `strict: optional boolean` - The search query. + 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. - - `sources: optional array of object { type, url }` + - `Custom object { name, type, allowed_callers, 3 more }` - The sources used in the search. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `type: "url"` + - `name: string` - The type of source. Always `url`. + The name of the custom tool, used to identify it in tool calls. - - `"url"` + - `type: "custom"` - - `url: string` + The type of the custom tool. Always `custom`. - The URL of the source. + - `"custom"` - - `OpenPage object { type, url }` + - `allowed_callers: optional array of "direct" or "programmatic"` - Action type "open_page" - Opens a specific URL from search results. + The tool invocation context(s). - - `type: "open_page"` + - `"direct"` - The action type. + - `"programmatic"` - - `"open_page"` + - `defer_loading: optional boolean` - - `url: optional string` + Whether this tool should be deferred and discovered via tool search. - The URL opened by the model. + - `description: optional string` - - `FindInPage object { pattern, type, url }` + Optional description of the custom tool, used to provide more context. - Action type "find_in_page": Searches for a pattern within a loaded page. + - `format: optional object { type } or object { definition, syntax, type }` - - `pattern: string` + The input format for the custom tool. Default is unconstrained text. - The pattern or text to search for within the page. + - `Text object { type }` - - `type: "find_in_page"` + Unconstrained free-form text. - The action type. + - `type: "text"` - - `"find_in_page"` + Unconstrained text format. Always `text`. - - `url: string` + - `"text"` - The URL of the page searched for the pattern. + - `Grammar object { definition, syntax, type }` - - `status: "in_progress" or "searching" or "completed" or "failed"` + A grammar defined by the user. - The status of the web search tool call. + - `definition: string` - - `"in_progress"` + The grammar definition. - - `"searching"` + - `syntax: "lark" or "regex"` - - `"completed"` + The syntax of the grammar definition. One of `lark` or `regex`. - - `"failed"` + - `"lark"` - - `type: "web_search_call"` + - `"regex"` - The type of the web search tool call. Always `web_search_call`. + - `type: "grammar"` - - `"web_search_call"` + 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"` - - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` + - `ToolSearch object { type, description, execution, parameters }` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + Hosted or BYOT tool search configuration for deferred tools. - - `id: string` + - `type: "tool_search"` - The unique ID of the computer call. + The type of the tool. Always `tool_search`. - - `call_id: string` + - `"tool_search"` - An identifier used when responding to the tool call with output. + - `description: optional string` - - `pending_safety_checks: array of object { id, code, message }` + Description shown to the model for a client-executed tool search tool. - The pending safety checks for the computer call. + - `execution: optional "server" or "client"` - - `id: string` + Whether tool search is executed by the server or by the client. - The ID of the pending safety check. + - `"server"` - - `code: optional string` + - `"client"` - The type of the pending safety check. + - `parameters: optional unknown` - - `message: optional string` + Parameter schema for a client-executed tool search tool. - Details about the pending safety check. + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - - `status: "in_progress" or "completed" or "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). - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `"in_progress"` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `"completed"` + - `"web_search_preview"` - - `"incomplete"` + - `"web_search_preview_2025_03_11"` - - `type: "computer_call"` + - `search_content_types: optional array of "text" or "image"` - The type of the computer call. Always `computer_call`. + - `"text"` - - `"computer_call"` + - `"image"` - - `action: optional BetaComputerAction` + - `search_context_size: optional "low" or "medium" or "high"` - A click action. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `actions: optional BetaComputerActionList` + - `"low"` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `"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 { id, call_id, output, 5 more }` + The type of location approximation. Always `approximate`. - - `id: string` + - `"approximate"` - The unique ID of the computer call tool output. + - `city: optional string` - - `call_id: string` + Free text input for the city of the user, e.g. `San Francisco`. - The ID of the computer tool call that produced the output. + - `country: optional string` - - `output: BetaResponseComputerToolCallOutputScreenshot` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - A computer screenshot image used with the computer use tool. + - `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 }` @@ -94282,16 +93208,12 @@ 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](https://platform.openai.com/docs/guides/conversation-state). + [managing context](/docs/guides/conversation-state). - `id: string` @@ -94355,111 +93277,23 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"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: "server" or "client"` - - Whether tool search was executed by the server or by the client. - - - `"server"` - - - `"client"` + - `Compaction object { encrypted_content, type, id, agent }` - - `status: "in_progress" or "completed" or "incomplete"` + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). - The status of the tool search call item that was recorded. + - `encrypted_content: string` - - `"in_progress"` + The encrypted content of the compaction summary. - - `"completed"` + - `type: "compaction"` - - `"incomplete"` + The type of the item. Always `compaction`. - - `type: "tool_search_call"` + - `"compaction"` - The type of the item. Always `tool_search_call`. + - `id: optional string` - - `"tool_search_call"` + The ID of the compaction item. - `agent: optional object { agent_name }` @@ -94469,2133 +93303,2042 @@ 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 }` - - `ToolSearchOutput object { id, call_id, execution, 5 more }` + An image generation request made by the model. - `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. + 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 output item that was recorded. + The status of the image generation call. - `"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. + - `"generating"` - - `parameters: map[unknown]` + - `"failed"` - A JSON schema object describing the parameters of the function. + - `type: "image_generation_call"` - - `strict: boolean` + The type of the image generation call. Always `image_generation_call`. - Whether strict parameter validation is enforced for this function tool. + - `"image_generation_call"` - - `type: "function"` + - `agent: optional object { agent_name }` - The type of the function tool. Always `function`. + The agent that produced this item. - - `"function"` + - `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). + - `CodeInterpreterCall object { id, code, container_id, 4 more }` - - `"direct"` + A tool call to run code. - - `"programmatic"` + - `id: string` - - `defer_loading: optional boolean` + The unique ID of the code interpreter tool call. - Whether this function is deferred and loaded via tool search. + - `code: string` - - `description: optional string` + The code to run, or null if not available. - A description of the function. Used by the model to determine whether or not to call the function. + - `container_id: string` - - `output_schema: optional map[unknown]` + The ID of the container used to run the code. - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `outputs: array of object { logs, type } or object { type, url }` - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are 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). + - `Logs object { logs, type }` - - `type: "file_search"` + The logs output from the code interpreter. - The type of the file search tool. Always `file_search`. + - `logs: string` - - `"file_search"` + The logs output from the code interpreter. - - `vector_store_ids: array of string` + - `type: "logs"` - The IDs of the vector stores to search. + The type of the output. Always `logs`. - - `filters: optional object { key, type, value } or object { filters, type }` + - `"logs"` - A filter to apply. + - `Image object { type, url }` - - `ComparisonFilter object { key, type, value }` + The image output from the code interpreter. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `type: "image"` - - `key: string` + The type of the output. Always `image`. - The key to compare against the value. + - `"image"` - - `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 image output from the code interpreter. - - `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 + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - - `"eq"` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `"ne"` + - `"in_progress"` - - `"gt"` + - `"completed"` - - `"gte"` + - `"incomplete"` - - `"lt"` + - `"interpreting"` - - `"lte"` + - `"failed"` - - `"in"` + - `type: "code_interpreter_call"` - - `"nin"` + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `value: string or number or boolean or array of string or number` + - `"code_interpreter_call"` - The value to compare against the attribute key; supports string, number, or boolean types. + - `agent: optional object { agent_name }` - - `string` + The agent that produced this item. - - `number` + - `agent_name: string` - - `boolean` + The canonical name of the agent that produced this item. - - `array of string or number` + - `LocalShellCall object { id, action, call_id, 3 more }` - - `string` + A tool call to run a command on the local shell. - - `number` + - `id: string` - - `CompoundFilter object { filters, type }` + The unique ID of the local shell call. - Combine multiple filters using `and` or `or`. + - `action: object { command, env, type, 3 more }` - - `filters: array of object { key, type, value } or unknown` + Execute a shell command on the server. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `command: array of string` - - `ComparisonFilter object { key, type, value }` + The command to run. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `env: map[string]` - - `key: string` + Environment variables to set for the command. - The key to compare against the value. + - `type: "exec"` - - `type: "eq" or "ne" or "gt" or 5 more` + The type of the local shell action. Always `exec`. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `"exec"` - - `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_ms: optional number` - - `"eq"` + Optional timeout in milliseconds for the command. - - `"ne"` + - `user: optional string` - - `"gt"` + Optional user to run the command as. - - `"gte"` + - `working_directory: optional string` - - `"lt"` + Optional working directory to run the command in. - - `"lte"` + - `call_id: string` - - `"in"` + The unique ID of the local shell tool call generated by the model. - - `"nin"` + - `status: "in_progress" or "completed" or "incomplete"` - - `value: string or number or boolean or array of string or number` + The status of the local shell call. - The value to compare against the attribute key; supports string, number, or boolean types. + - `"in_progress"` - - `string` + - `"completed"` - - `number` + - `"incomplete"` - - `boolean` + - `type: "local_shell_call"` - - `array of string or number` + The type of the local shell call. Always `local_shell_call`. - - `string` + - `"local_shell_call"` - - `number` + - `agent: optional object { agent_name }` - - `unknown` + The agent that produced this item. - - `type: "and" or "or"` + - `agent_name: string` - Type of operation: `and` or `or`. + The canonical name of the agent that produced this item. - - `"and"` + - `LocalShellCallOutput object { id, output, type, 2 more }` - - `"or"` + The output of a local shell tool call. - - `max_num_results: optional number` + - `id: string` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + The unique ID of the local shell tool call generated by the model. - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `output: string` - Ranking options for search. + A JSON string of the output of the local shell tool call. - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `type: "local_shell_call_output"` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + The type of the local shell tool call output. Always `local_shell_call_output`. - - `embedding_weight: number` + - `"local_shell_call_output"` - 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. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"auto"` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `"default-2024-11-15"` + - `"in_progress"` - - `score_threshold: optional number` + - `"completed"` - 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. + - `"incomplete"` - - `Computer object { type }` + - `ShellCall object { action, call_id, type, 5 more }` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + A tool representing a request to execute one or more shell commands. - - `type: "computer"` + - `action: object { commands, max_output_length, timeout_ms }` - The type of the computer tool. Always `computer`. + The shell commands and limits that describe how to run the tool call. - - `"computer"` + - `commands: array of string` - - `ComputerUsePreview object { display_height, display_width, environment, type }` + Ordered shell commands for the execution environment to run. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `max_output_length: optional number` - - `display_height: number` + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - The height of the computer display. + - `timeout_ms: optional number` - - `display_width: number` + Maximum wall-clock time in milliseconds to allow the shell commands to run. - The width of the computer display. + - `call_id: string` - - `environment: "windows" or "mac" or "linux" or 2 more` + The unique ID of the shell tool call generated by the model. - The type of computer environment to control. + - `type: "shell_call"` - - `"windows"` + The type of the item. Always `shell_call`. - - `"mac"` + - `"shell_call"` - - `"linux"` + - `id: optional string` - - `"ubuntu"` + The unique ID of the shell tool call. Populated when this item is returned via API. - - `"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 }` + - `caller: optional object { type } or object { caller_id, type }` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The execution context that produced this tool call. - - `type: "web_search" or "web_search_2025_08_26"` + - `Direct object { type }` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `type: "direct"` - - `"web_search"` + The caller type. Always `direct`. - - `"web_search_2025_08_26"` + - `"direct"` - - `filters: optional object { allowed_domains }` + - `Program object { caller_id, type }` - Filters for the search. + - `caller_id: string` - - `allowed_domains: optional array of string` + The call ID of the program item that produced this tool call. - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `type: "program"` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + The caller type. Always `program`. - - `search_context_size: optional "low" or "medium" or "high"` + - `"program"` - 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. + - `environment: optional BetaLocalEnvironment or BetaContainerReference` - - `"low"` + The environment to execute the shell commands in. - - `"medium"` + - `BetaLocalEnvironment object { type, skills }` - - `"high"` + - `BetaContainerReference object { container_id, type }` - - `user_location: optional object { city, country, region, 2 more }` + - `status: optional "in_progress" or "completed" or "incomplete"` - The approximate location of the user. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `city: optional string` + - `"in_progress"` - Free text input for the city of the user, e.g. `San Francisco`. + - `"completed"` - - `country: optional string` + - `"incomplete"` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `ShellCallOutput object { call_id, output, type, 5 more }` - - `region: optional string` + The streamed output items emitted by a shell tool call. - Free text input for the region of the user, e.g. `California`. + - `call_id: string` - - `timezone: optional string` + The unique ID of the shell tool call generated by the model. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `output: array of BetaResponseFunctionShellCallOutputContent` - - `type: optional "approximate"` + Captured chunks of stdout and stderr output, along with their associated outcomes. - The type of location approximation. Always `approximate`. + - `outcome: object { type } or object { exit_code, type }` - - `"approximate"` + The exit or timeout outcome associated with this shell call. - - `Mcp object { server_label, type, allowed_callers, 9 more }` + - `Timeout object { type }` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + Indicates that the shell call exceeded its configured time limit. - - `server_label: string` + - `type: "timeout"` - A label for this MCP server, used to identify it in tool calls. + The outcome type. Always `timeout`. - - `type: "mcp"` + - `"timeout"` - The type of the MCP tool. Always `mcp`. + - `Exit object { exit_code, type }` - - `"mcp"` + Indicates that the shell commands finished and returned an exit code. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `exit_code: number` - The tool invocation context(s). + The exit code returned by the shell process. - - `"direct"` + - `type: "exit"` - - `"programmatic"` + The outcome type. Always `exit`. - - `allowed_tools: optional array of string or object { read_only, tool_names }` + - `"exit"` - List of allowed tool names or a filter object. + - `stderr: string` - - `McpAllowedTools = array of string` + Captured stderr output for the shell call. - A string array of allowed tool names + - `stdout: string` - - `McpToolFilter object { read_only, tool_names }` + Captured stdout output for the shell call. - A filter object to specify which tools are allowed. + - `type: "shell_call_output"` - - `read_only: optional boolean` + The type of the item. Always `shell_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. + - `"shell_call_output"` - - `tool_names: optional array of string` + - `id: optional string` - List of allowed tool names. + The unique ID of the shell tool call output. Populated when this item is returned via API. - - `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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + The canonical name of the agent that produced this item. - Currently supported `connector_id` values are: + - `caller: optional object { type } or 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` + The execution context that produced this tool call. - - `"connector_dropbox"` + - `Direct object { type }` - - `"connector_gmail"` + - `type: "direct"` - - `"connector_googlecalendar"` + The caller type. Always `direct`. - - `"connector_googledrive"` + - `"direct"` - - `"connector_microsoftteams"` + - `Program object { caller_id, type }` - - `"connector_outlookcalendar"` + - `caller_id: string` - - `"connector_outlookemail"` + The call ID of the program item that produced this tool call. - - `"connector_sharepoint"` + - `type: "program"` - - `defer_loading: optional boolean` + The caller type. Always `program`. - Whether this MCP tool is deferred and discovered via tool search. + - `"program"` - - `headers: optional map[string]` + - `max_output_length: optional number` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + The maximum number of UTF-8 characters captured for this shell call's combined output. - - `require_approval: optional object { always, never } or "always" or "never"` + - `status: optional "in_progress" or "completed" or "incomplete"` - Specify which of the MCP server's tools require approval. + The status of the shell call output. - - `McpToolApprovalFilter object { always, never }` + - `"in_progress"` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `"completed"` - - `always: optional object { read_only, tool_names }` + - `"incomplete"` - A filter object to specify which tools are allowed. + - `ApplyPatchCall object { call_id, operation, status, 4 more }` - - `read_only: optional boolean` + A tool call representing a request to create, delete, or update files using diff patches. - 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. + - `call_id: string` - - `tool_names: optional array of string` + The unique ID of the apply patch tool call generated by the model. - List of allowed tool names. + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - - `never: optional object { read_only, tool_names }` + The specific create, delete, or update instruction for the apply_patch tool call. - A filter object to specify which tools are allowed. + - `CreateFile object { diff, path, type }` - - `read_only: optional boolean` + Instruction for creating a new 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. + - `diff: string` - - `tool_names: optional array of string` + Unified diff content to apply when creating the file. - List of allowed tool names. + - `path: string` - - `McpToolApprovalSetting = "always" or "never"` + Path of the file to create relative to the workspace root. - 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: "create_file"` - - `"always"` + The operation type. Always `create_file`. - - `"never"` + - `"create_file"` - - `server_description: optional string` + - `DeleteFile object { path, type }` - Optional description of the MCP server, used to provide more context. + Instruction for deleting an existing file via the apply_patch tool. - - `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 delete relative to the workspace root. - - `tunnel_id: optional string` + - `type: "delete_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 `delete_file`. - - `CodeInterpreter object { container, type, allowed_callers }` + - `"delete_file"` - A tool that runs Python code to help generate a response to a prompt. + - `UpdateFile object { diff, path, type }` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + Instruction for updating an existing 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` + Unified diff content to apply to the existing file. - The container ID. + - `path: string` - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + Path of the file to update relative to the workspace root. - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `type: "update_file"` - - `type: "auto"` + The operation type. Always `update_file`. - Always `auto`. + - `"update_file"` - - `"auto"` + - `status: "in_progress" or "completed"` - - `file_ids: optional array of string` + The status of the apply patch tool call. One of `in_progress` or `completed`. - 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. + - `type: "apply_patch_call"` - - `"1g"` + The type of the item. Always `apply_patch_call`. - - `"4g"` + - `"apply_patch_call"` - - `"16g"` + - `id: optional string` - - `"64g"` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `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). + The caller type. Always `direct`. - `"direct"` - - `"programmatic"` - - - `ProgrammaticToolCalling object { type }` - - - `type: "programmatic_tool_calling"` + - `Program object { caller_id, type }` - The type of the tool. Always `programmatic_tool_calling`. + - `caller_id: string` - - `"programmatic_tool_calling"` + The call ID of the program item that produced this tool call. - - `ImageGeneration object { type, action, background, 9 more }` + - `type: "program"` - A tool that generates images using the GPT image models. + The caller type. Always `program`. - - `type: "image_generation"` + - `"program"` - The type of the image generation tool. Always `image_generation`. + - `ApplyPatchCallOutput object { call_id, status, type, 4 more }` - - `"image_generation"` + The streamed output emitted by an apply patch tool call. - - `action: optional "generate" or "edit" or "auto"` + - `call_id: string` - Whether to generate a new image or edit an existing image. Default: `auto`. + The unique ID of the apply patch tool call generated by the model. - - `"generate"` + - `status: "completed" or "failed"` - - `"edit"` + The status of the apply patch tool call output. One of `completed` or `failed`. - - `"auto"` + - `"completed"` - - `background: optional "transparent" or "opaque" or "auto"` + - `"failed"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + - `type: "apply_patch_call_output"` - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + The type of the item. Always `apply_patch_call_output`. - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `"apply_patch_call_output"` - - `"transparent"` + - `id: optional string` - - `"opaque"` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `"auto"` + - `agent: optional object { agent_name }` - - `input_fidelity: optional "high" or "low"` + 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`. + - `agent_name: string` - - `"high"` + The canonical name of the agent that produced this item. - - `"low"` + - `caller: optional object { type } or object { caller_id, type }` - - `input_image_mask: optional object { file_id, image_url }` + The execution context that produced this tool call. - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `Direct object { type }` - - `file_id: optional string` + - `type: "direct"` - File ID for the mask image. + The caller type. Always `direct`. - - `image_url: optional string` + - `"direct"` - Base64-encoded mask image. + - `Program object { caller_id, type }` - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `caller_id: string` - The image generation model to use. Default: `gpt-image-1`. + The call ID of the program item that produced this tool call. - - `string` + - `type: "program"` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + The caller type. Always `program`. - The image generation model to use. Default: `gpt-image-1`. + - `"program"` - - `"gpt-image-1"` + - `output: optional string` - - `"gpt-image-1-mini"` + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - - `"gpt-image-2"` + - `McpListTools object { id, server_label, tools, 3 more }` - - `"gpt-image-2-2026-04-21"` + A list of tools available on an MCP server. - - `"gpt-image-1.5"` + - `id: string` - - `"chatgpt-image-latest"` + The unique ID of the list. - - `moderation: optional "auto" or "low"` + - `server_label: string` - Moderation level for the generated image. Default: `auto`. + The label of the MCP server. - - `"auto"` + - `tools: array of object { input_schema, name, annotations, description }` - - `"low"` + The tools available on the server. - - `output_compression: optional number` + - `input_schema: unknown` - Compression level for the output image. Default: 100. + The JSON schema describing the tool's input. - - `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. - - `"png"` + - `annotations: optional unknown` - - `"webp"` + Additional annotations about the tool. - - `"jpeg"` + - `description: optional string` - - `partial_images: optional number` + The description of the tool. - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `type: "mcp_list_tools"` - - `quality: optional "low" or "medium" or "high" or "auto"` + The type of the item. Always `mcp_list_tools`. - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `"mcp_list_tools"` - - `"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"` + - `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`. + Error message if the server could not list tools. - - `string` + - `McpApprovalRequest object { id, arguments, name, 3 more }` - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + A request for human approval of a tool invocation. - 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 approval request. - - `"1024x1536"` + - `arguments: string` - - `"1536x1024"` + A JSON string of arguments for the tool. - - `"auto"` + - `name: string` - - `LocalShell object { type }` + The name of the tool to run. - A tool that allows the model to execute shell commands in a local environment. + - `server_label: string` - - `type: "local_shell"` + The label of the MCP server making the request. - The type of the local shell tool. Always `local_shell`. + - `type: "mcp_approval_request"` - - `"local_shell"` + The type of the item. Always `mcp_approval_request`. - - `Shell object { type, allowed_callers, environment }` + - `"mcp_approval_request"` - A tool that allows the model to execute shell commands. + - `agent: optional object { agent_name }` - - `type: "shell"` + The agent that produced this item. - 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"` + - `McpApprovalResponse object { approval_request_id, approve, type, 3 more }` - The tool invocation context(s). + A response to an MCP approval request. - - `"direct"` + - `approval_request_id: string` - - `"programmatic"` + The ID of the approval request being answered. - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + - `approve: boolean` - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + Whether the request was approved. - - `BetaLocalEnvironment object { type, skills }` + - `type: "mcp_approval_response"` - - `BetaContainerReference object { container_id, type }` + The type of the item. Always `mcp_approval_response`. - - `Custom object { name, type, allowed_callers, 3 more }` + - `"mcp_approval_response"` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `id: optional string` - - `name: string` + The unique ID of the approval response - The name of the custom tool, used to identify it in tool calls. + - `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"` + - `reason: optional string` - The tool invocation context(s). + Optional reason for the decision. - - `"direct"` + - `McpCall object { id, arguments, name, 7 more }` - - `"programmatic"` + An invocation of a tool on an MCP server. - - `defer_loading: optional boolean` + - `id: string` - Whether this tool should be deferred and discovered via tool search. + The unique ID of the tool call. - - `description: optional string` + - `arguments: string` - Optional description of the custom tool, used to provide more context. + A JSON string of the arguments passed to the tool. - - `format: optional object { type } or object { definition, syntax, type }` + - `name: string` - The input format for the custom tool. Default is unconstrained text. + The name of the tool that was run. - - `Text object { type }` + - `server_label: string` - Unconstrained free-form text. + The label of the MCP server running the tool. - - `type: "text"` + - `type: "mcp_call"` - Unconstrained text format. Always `text`. + The type of the item. Always `mcp_call`. - - `"text"` + - `"mcp_call"` - - `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"` + - `approval_request_id: optional string` - The syntax of the grammar definition. One of `lark` or `regex`. + 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. - - `"lark"` + - `error: optional string` - - `"regex"` + The error from the tool call, if any. - - `type: "grammar"` + - `output: optional string` - Grammar format. Always `grammar`. + The output from the tool call. - - `"grammar"` + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - - `Namespace object { description, name, tools, type }` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - Groups function/custom tools under a shared namespace. + - `"in_progress"` - - `description: string` + - `"completed"` - A description of the namespace shown to the model. + - `"incomplete"` - - `name: string` + - `"calling"` - The namespace name used in tool calls (for example, `crm`). + - `"failed"` - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + - `CustomToolCallOutput object { call_id, output, type, 3 more }` - The function/custom tools available inside this namespace. + The output of a custom tool call from your code, being sent back to the model. - - `Function object { name, type, allowed_callers, 5 more }` + - `call_id: string` - - `name: string` + The call ID, used to map this custom tool call output to a custom tool call. - - `type: "function"` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `"function"` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `StringOutput = string` - The tool invocation context(s). + A string of the output of the custom tool call. - - `"direct"` + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `"programmatic"` + Text, image, or file output of the custom tool call. - - `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` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `output_schema: optional map[unknown]` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `parameters: optional unknown` + A file input to the model. - - `strict: optional boolean` + - `type: "custom_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. + 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](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `id: optional string` - - `name: string` + The unique ID of the custom tool call output in the OpenAI platform. - 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"` + - `CustomToolCall object { call_id, input, name, 5 more }` - Unconstrained text format. Always `text`. + A call to a custom tool created by the model. - - `"text"` + - `call_id: string` - - `Grammar object { definition, syntax, type }` + An identifier used to map this custom tool call to a tool call output. - A grammar defined by the user. + - `input: string` - - `definition: string` + The input for the custom tool call generated by the model. - The grammar definition. + - `name: string` - - `syntax: "lark" or "regex"` + The name of the custom tool being called. - The syntax of the grammar definition. One of `lark` or `regex`. + - `type: "custom_tool_call"` - - `"lark"` + The type of the custom tool call. Always `custom_tool_call`. - - `"regex"` + - `"custom_tool_call"` - - `type: "grammar"` + - `id: optional string` - Grammar format. Always `grammar`. + The unique ID of the custom tool call in the OpenAI platform. - - `"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 }` + - `caller: optional object { type } or object { caller_id, type }` - Hosted or BYOT tool search configuration for deferred tools. + The execution context that produced this tool call. - - `type: "tool_search"` + - `Direct object { type }` - The type of the tool. Always `tool_search`. + - `type: "direct"` - - `"tool_search"` + - `"direct"` - - `description: optional string` + - `Program object { caller_id, type }` - Description shown to the model for a client-executed tool search tool. + - `caller_id: string` - - `execution: optional "server" or "client"` + The call ID of the program item that produced this tool call. - Whether tool search is executed by the server or by the client. + - `type: "program"` - - `"server"` + - `"program"` - - `"client"` + - `namespace: optional string` - - `parameters: optional unknown` + The namespace of the custom tool being called. - Parameter schema for a client-executed tool search tool. + - `CompactionTrigger object { type, agent }` - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + Compacts the current context. Must be the final input 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). + - `type: "compaction_trigger"` - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + The type of the item. Always `compaction_trigger`. - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `"compaction_trigger"` - - `"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"` + - `ItemReference object { id, agent, type }` - - `search_context_size: optional "low" or "medium" or "high"` + An internal identifier for an item to 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. + - `id: string` - - `"low"` + The ID of the item to reference. - - `"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"` + - `type: optional "item_reference"` - The type of location approximation. Always `approximate`. + The type of item to reference. Always `item_reference`. - - `"approximate"` + - `"item_reference"` - - `city: optional string` + - `Program object { id, call_id, code, 3 more }` - Free text input for the city of the user, e.g. `San Francisco`. + - `id: string` - - `country: optional string` + The unique ID of this program item. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `call_id: string` - - `region: optional string` + The stable call ID of the program item. - Free text input for the region of the user, e.g. `California`. + - `code: string` - - `timezone: optional string` + The JavaScript source executed by programmatic tool calling. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `fingerprint: string` - - `ApplyPatch object { type, allowed_callers }` + Opaque program replay fingerprint that must be round-tripped. - Allows the assistant to create, delete, or update files using unified diffs. + - `type: "program"` - - `type: "apply_patch"` + The item type. Always `program`. - The type of the tool. Always `apply_patch`. + - `"program"` - - `"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"` + - `ProgramOutput object { id, call_id, result, 3 more }` - - `type: "tool_search_output"` + - `id: string` - The type of the item. Always `tool_search_output`. + The unique ID of this program output item. - - `"tool_search_output"` + - `call_id: string` - - `agent: optional object { agent_name }` + The call ID of the program item. - The agent that produced this item. + - `result: string` - - `agent_name: string` + The result produced by the program item. - The canonical name of the agent that produced this item. + - `status: "completed" or "incomplete"` - - `created_by: optional string` + The terminal status of the program output. - The identifier of the actor that created the item. + - `"completed"` - - `AdditionalTools object { id, role, tools, 2 more }` + - `"incomplete"` - - `id: string` + - `type: "program_output"` - The unique ID of the additional tools item. + The item type. Always `program_output`. - - `role: "unknown" or "user" or "assistant" or 5 more` + - `"program_output"` - The role that provided the additional tools. + - `agent: optional object { agent_name }` - - `"unknown"` + The agent that produced this item. - - `"user"` + - `agent_name: string` - - `"assistant"` + The canonical name of the agent that produced this item. - - `"system"` + - `metadata: map[string]` - - `"critic"` + 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. - - `"discriminator"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `"developer"` + - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` - - `"tool"` + 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. - - `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.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more` - The additional tool definitions made available at this item. + 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. - - `Function object { name, parameters, strict, 5 more }` + - `"gpt-5.6-sol"` - 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.6-terra"` - - `name: string` + - `"gpt-5.6-luna"` - The name of the function to call. + - `"gpt-5.4"` - - `parameters: map[unknown]` + - `"gpt-5.4-mini"` - A JSON schema object describing the parameters of the function. + - `"gpt-5.4-nano"` - - `strict: boolean` + - `"gpt-5.4-mini-2026-03-17"` - Whether strict parameter validation is enforced for this function tool. + - `"gpt-5.4-nano-2026-03-17"` - - `type: "function"` + - `"gpt-5.3-chat-latest"` - The type of the function tool. Always `function`. + - `"gpt-5.2"` - - `"function"` + - `"gpt-5.2-2025-12-11"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"gpt-5.2-chat-latest"` - The tool invocation context(s). + - `"gpt-5.2-pro"` - - `"direct"` + - `"gpt-5.2-pro-2025-12-11"` - - `"programmatic"` + - `"gpt-5.1"` - - `defer_loading: optional boolean` + - `"gpt-5.1-2025-11-13"` - Whether this function is deferred and loaded via tool search. + - `"gpt-5.1-codex"` - - `description: optional string` + - `"gpt-5.1-mini"` - A description of the function. Used by the model to determine whether or not to call the function. + - `"gpt-5.1-chat-latest"` - - `output_schema: optional map[unknown]` + - `"gpt-5"` - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `"gpt-5-mini"` - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + - `"gpt-5-nano"` - 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-5-2025-08-07"` - - `type: "file_search"` + - `"gpt-5-mini-2025-08-07"` - The type of the file search tool. Always `file_search`. + - `"gpt-5-nano-2025-08-07"` - - `"file_search"` + - `"gpt-5-chat-latest"` - - `vector_store_ids: array of string` + - `"gpt-4.1"` - The IDs of the vector stores to search. + - `"gpt-4.1-mini"` - - `filters: optional object { key, type, value } or object { filters, type }` + - `"gpt-4.1-nano"` - A filter to apply. + - `"gpt-4.1-2025-04-14"` - - `ComparisonFilter object { key, type, value }` + - `"gpt-4.1-mini-2025-04-14"` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `"gpt-4.1-nano-2025-04-14"` - - `key: string` + - `"o4-mini"` - The key to compare against the value. + - `"o4-mini-2025-04-16"` - - `type: "eq" or "ne" or "gt" or 5 more` + - `"o3"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `"o3-2025-04-16"` - - `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-mini"` - - `"eq"` + - `"o3-mini-2025-01-31"` - - `"ne"` + - `"o1"` - - `"gt"` + - `"o1-2024-12-17"` - - `"gte"` + - `"o1-preview"` - - `"lt"` + - `"o1-preview-2024-09-12"` - - `"lte"` + - `"o1-mini"` - - `"in"` + - `"o1-mini-2024-09-12"` - - `"nin"` + - `"gpt-4o"` - - `value: string or number or boolean or array of string or number` + - `"gpt-4o-2024-11-20"` - The value to compare against the attribute key; supports string, number, or boolean types. + - `"gpt-4o-2024-08-06"` - - `string` + - `"gpt-4o-2024-05-13"` - - `number` + - `"gpt-4o-audio-preview"` - - `boolean` + - `"gpt-4o-audio-preview-2024-10-01"` - - `array of string or number` + - `"gpt-4o-audio-preview-2024-12-17"` - - `string` + - `"gpt-4o-audio-preview-2025-06-03"` - - `number` + - `"gpt-4o-mini-audio-preview"` - - `CompoundFilter object { filters, type }` + - `"gpt-4o-mini-audio-preview-2024-12-17"` - Combine multiple filters using `and` or `or`. + - `"gpt-4o-search-preview"` - - `filters: array of object { key, type, value } or unknown` + - `"gpt-4o-mini-search-preview"` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `"gpt-4o-search-preview-2025-03-11"` - - `ComparisonFilter object { key, type, value }` + - `"gpt-4o-mini-search-preview-2025-03-11"` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `"chatgpt-4o-latest"` - - `key: string` + - `"codex-mini-latest"` - The key to compare against the value. + - `"gpt-4o-mini"` - - `type: "eq" or "ne" or "gt" or 5 more` + - `"gpt-4o-mini-2024-07-18"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `"gpt-4-turbo"` - - `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-turbo-2024-04-09"` - - `"eq"` + - `"gpt-4-0125-preview"` - - `"ne"` + - `"gpt-4-turbo-preview"` - - `"gt"` + - `"gpt-4-1106-preview"` - - `"gte"` + - `"gpt-4-vision-preview"` - - `"lt"` + - `"gpt-4"` - - `"lte"` + - `"gpt-4-0314"` - - `"in"` + - `"gpt-4-0613"` - - `"nin"` + - `"gpt-4-32k"` - - `value: string or number or boolean or array of string or number` + - `"gpt-4-32k-0314"` - The value to compare against the attribute key; supports string, number, or boolean types. + - `"gpt-4-32k-0613"` - - `string` + - `"gpt-3.5-turbo"` - - `number` + - `"gpt-3.5-turbo-16k"` - - `boolean` + - `"gpt-3.5-turbo-0301"` - - `array of string or number` + - `"gpt-3.5-turbo-0613"` - - `string` + - `"gpt-3.5-turbo-1106"` - - `number` + - `"gpt-3.5-turbo-0125"` - - `unknown` + - `"gpt-3.5-turbo-16k-0613"` - - `type: "and" or "or"` + - `"o1-pro"` - Type of operation: `and` or `or`. + - `"o1-pro-2025-03-19"` - - `"and"` + - `"o3-pro"` - - `"or"` + - `"o3-pro-2025-06-10"` - - `max_num_results: optional number` + - `"o3-deep-research"` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `"o3-deep-research-2025-06-26"` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `"o4-mini-deep-research"` - Ranking options for search. + - `"o4-mini-deep-research-2025-06-26"` - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `"computer-use-preview"` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `"computer-use-preview-2025-03-11"` - - `embedding_weight: number` + - `"gpt-5-codex"` - The weight of the embedding in the reciprocal ranking fusion. + - `"gpt-5-pro"` - - `text_weight: number` + - `"gpt-5-pro-2025-10-06"` - The weight of the text in the reciprocal ranking fusion. + - `"gpt-5.1-codex-max"` - - `ranker: optional "auto" or "default-2024-11-15"` + - `string` - The ranker to use for the file search. + - `object: "response"` - - `"auto"` + The object type of this resource - always set to `response`. - - `"default-2024-11-15"` + - `"response"` - - `score_threshold: optional number` + - `output: array of BetaResponseOutputItem` - 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 array of content items generated by the model. - - `Computer object { type }` + - 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. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `BetaResponseOutputMessage object { id, content, role, 4 more }` - - `type: "computer"` + An output message from the model. - The type of the computer tool. Always `computer`. + - `FileSearchCall object { id, queries, status, 3 more }` - - `"computer"` + The results of a file search tool call. See the + [file search guide](/docs/guides/tools-file-search) for more information. - - `ComputerUsePreview object { display_height, display_width, environment, type }` + - `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 file search tool call. - - `display_height: number` + - `queries: array of string` - The height of the computer display. + The queries used to search for files. - - `display_width: number` + - `status: "in_progress" or "searching" or "completed" or 2 more` - The width of the computer display. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `environment: "windows" or "mac" or "linux" or 2 more` + - `"in_progress"` - The type of computer environment to control. + - `"searching"` - - `"windows"` + - `"completed"` - - `"mac"` + - `"incomplete"` - - `"linux"` + - `"failed"` - - `"ubuntu"` + - `type: "file_search_call"` - - `"browser"` + The type of the file search tool call. Always `file_search_call`. - - `type: "computer_use_preview"` + - `"file_search_call"` - The type of the computer use tool. Always `computer_use_preview`. + - `agent: optional object { agent_name }` - - `"computer_use_preview"` + The agent that produced this item. - - `WebSearch object { type, filters, search_context_size, user_location }` + - `agent_name: string` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The canonical name of the agent that produced this item. - - `type: "web_search" or "web_search_2025_08_26"` + - `results: optional array of object { attributes, file_id, filename, 2 more }` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + The results of the file search tool call. - - `"web_search"` + - `attributes: optional map[string or number or boolean]` - - `"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. Keys are strings + with a maximum length of 64 characters. Values are strings with a maximum + length of 512 characters, booleans, or numbers. - - `filters: optional object { allowed_domains }` + - `string` - Filters for the search. + - `number` - - `allowed_domains: optional array of string` + - `boolean` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `file_id: optional string` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + The unique ID of the file. - - `search_context_size: optional "low" or "medium" or "high"` + - `filename: 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 name of the file. - - `"low"` + - `score: optional number` - - `"medium"` + The relevance score of the file - a value between 0 and 1. - - `"high"` + - `text: optional string` - - `user_location: optional object { city, country, region, 2 more }` + The text that was retrieved from the file. - The approximate location of the user. + - `FunctionCall object { arguments, call_id, name, 6 more }` - - `city: optional string` + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. - Free text input for the city of the user, e.g. `San Francisco`. + - `arguments: string` - - `country: optional string` + A JSON string of the arguments to pass to the function. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `call_id: string` - - `region: optional string` + The unique ID of the function tool call generated by the model. - Free text input for the region of the user, e.g. `California`. + - `name: string` - - `timezone: optional string` + The name of the function to run. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `type: "function_call"` - - `type: optional "approximate"` + The type of the function tool call. Always `function_call`. - The type of location approximation. Always `approximate`. + - `"function_call"` - - `"approximate"` + - `id: optional string` - - `Mcp object { server_label, type, allowed_callers, 9 more }` + The unique ID of the function tool call. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/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 }` + - `namespace: optional string` - A filter object to specify which tools are allowed. + The namespace of the function to run. - - `read_only: optional boolean` + - `status: optional "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. + - `FunctionCallOutput object { id, call_id, output, 5 more }` - - `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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + The unique ID of the function call tool output. - Currently supported `connector_id` values are: + - `call_id: string` - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + The unique ID of the function tool call generated by the model. - - `"connector_dropbox"` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `"connector_gmail"` + The output from the function call generated by your code. + Can be a string or an list of output content. - - `"connector_googlecalendar"` + - `StringOutput = string` - - `"connector_googledrive"` + A string of the output of the function call. - - `"connector_microsoftteams"` + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `"connector_outlookcalendar"` + Text, image, or file output of the function call. - - `"connector_outlookemail"` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `"connector_sharepoint"` + A text input to the model. - - `defer_loading: optional boolean` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - Whether this MCP tool is deferred and discovered via tool search. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `headers: optional map[string]` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + A file input to the model. - - `require_approval: optional object { always, never } or "always" or "never"` + - `status: "in_progress" or "completed" or "incomplete"` - Specify which of the MCP server's tools require approval. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `McpToolApprovalFilter object { always, never }` + - `"in_progress"` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `"completed"` - - `always: optional object { read_only, tool_names }` + - `"incomplete"` - A filter object to specify which tools are allowed. + - `type: "function_call_output"` - - `read_only: optional boolean` + The type of the function tool call output. Always `function_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. + - `"function_call_output"` - - `tool_names: optional array of string` + - `agent: optional object { agent_name }` - List of allowed tool names. + The agent that produced this item. - - `never: 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` + - `caller: optional object { type } or 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. + The execution context that produced this tool call. - - `tool_names: optional array of string` + - `Direct object { type }` - List of allowed tool names. + - `type: "direct"` - - `McpToolApprovalSetting = "always" or "never"` + The caller type. Always `direct`. - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + - `"direct"` - - `"always"` + - `Program object { caller_id, type }` - - `"never"` + - `caller_id: string` - - `server_description: optional string` + The call ID of the program item that produced this tool call. - Optional description of the MCP server, used to provide more context. + - `type: "program"` - - `server_url: optional string` + The caller type. Always `program`. - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `"program"` - - `tunnel_id: optional string` + - `created_by: 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. + The identifier of the actor that created the item. - - `CodeInterpreter object { container, type, allowed_callers }` + - `AgentMessage object { id, author, content, 3 more }` - A tool that runs Python code to help generate a response to a prompt. + - `id: string` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + The unique ID of the agent 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. + - `author: string` - - `string` + The sending agent identity. - The container ID. + - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + Encrypted content sent between agents. - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `type: "auto"` + A text input to the model. - Always `auto`. + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - - `"auto"` + A text output from the model. - - `file_ids: optional array of string` + - `Text object { text, type }` - An optional list of uploaded files to make available to your code. + A text content. - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `text: string` - The memory limit for the code interpreter container. + - `type: "text"` - - `"1g"` + - `"text"` - - `"4g"` + - `SummaryText object { text, type }` - - `"16g"` + A summary text from the model. - - `"64g"` + - `text: string` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + A summary of the reasoning output from the model so far. - Network access policy for the container. + - `type: "summary_text"` - - `BetaContainerNetworkPolicyDisabled object { type }` + The type of the object. Always `summary_text`. - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `"summary_text"` - - `type: "code_interpreter"` + - `ReasoningText object { text, type }` - The type of the code interpreter tool. Always `code_interpreter`. + Reasoning text from the model. - - `"code_interpreter"` + - `text: string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The reasoning text from the model. - The tool invocation context(s). + - `type: "reasoning_text"` - - `"direct"` + The type of the reasoning text. Always `reasoning_text`. - - `"programmatic"` + - `"reasoning_text"` - - `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`. + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `"programmatic_tool_calling"` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `ImageGeneration object { type, action, background, 9 more }` + - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` - A tool that generates images using the GPT image models. + A screenshot of a computer. - - `type: "image_generation"` + - `detail: "low" or "high" or "auto" or "original"` - The type of the image generation tool. Always `image_generation`. + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `"image_generation"` + - `"low"` - - `action: optional "generate" or "edit" or "auto"` + - `"high"` - Whether to generate a new image or edit an existing image. Default: `auto`. + - `"auto"` - - `"generate"` + - `"original"` - - `"edit"` + - `file_id: string` - - `"auto"` + The identifier of an uploaded file that contains the screenshot. - - `background: optional "transparent" or "opaque" or "auto"` + - `image_url: string` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + The URL of the screenshot image. - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + - `type: "computer_screenshot"` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `"transparent"` + - `"computer_screenshot"` - - `"opaque"` + - `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. - - `input_fidelity: optional "high" or "low"` + - `mode: "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`. + The breakpoint mode. Always `explicit`. - - `"high"` + - `"explicit"` - - `"low"` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `input_image_mask: optional object { file_id, image_url }` + A file input to the model. - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `EncryptedContent object { encrypted_content, type }` - - `file_id: optional string` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - File ID for the mask image. + - `encrypted_content: string` - - `image_url: optional string` + Opaque encrypted content. - Base64-encoded mask image. + - `type: "encrypted_content"` - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + The type of the input item. Always `encrypted_content`. - The image generation model to use. Default: `gpt-image-1`. + - `"encrypted_content"` - - `string` + - `recipient: string` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + The destination agent identity. - The image generation model to use. Default: `gpt-image-1`. + - `type: "agent_message"` - - `"gpt-image-1"` + The type of the item. Always `agent_message`. - - `"gpt-image-1-mini"` + - `"agent_message"` - - `"gpt-image-2"` + - `agent: optional object { agent_name }` - - `"gpt-image-2-2026-04-21"` + The agent that produced this item. - - `"gpt-image-1.5"` + - `agent_name: string` - - `"chatgpt-image-latest"` + The canonical name of the agent that produced this item. - - `moderation: optional "auto" or "low"` + - `MultiAgentCall object { id, action, arguments, 3 more }` - Moderation level for the generated image. Default: `auto`. + - `id: string` - - `"auto"` + The unique ID of the multi-agent call item. - - `"low"` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `output_compression: optional number` + The multi-agent action to execute. - Compression level for the output image. Default: 100. + - `"spawn_agent"` - - `output_format: optional "png" or "webp" or "jpeg"` + - `"interrupt_agent"` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `"list_agents"` - - `"png"` + - `"send_message"` - - `"webp"` + - `"followup_task"` - - `"jpeg"` + - `"wait_agent"` - - `partial_images: optional number` + - `arguments: string` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + The JSON string of arguments generated for the action. - - `quality: optional "low" or "medium" or "high" or "auto"` + - `call_id: string` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + The unique ID linking this call to its output. - - `"low"` + - `type: "multi_agent_call"` - - `"medium"` + The type of the multi-agent call. Always `multi_agent_call`. - - `"high"` + - `"multi_agent_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"` + - `MultiAgentCallOutput object { id, action, call_id, 3 more }` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `id: string` - - `"1024x1024"` + The unique ID of the multi-agent call output item. - - `"1024x1536"` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `"1536x1024"` + The multi-agent action that produced this result. - - `"auto"` + - `"spawn_agent"` - - `LocalShell object { type }` + - `"interrupt_agent"` - A tool that allows the model to execute shell commands in a local environment. + - `"list_agents"` - - `type: "local_shell"` + - `"send_message"` - The type of the local shell tool. Always `local_shell`. + - `"followup_task"` - - `"local_shell"` + - `"wait_agent"` - - `Shell object { type, allowed_callers, environment }` + - `call_id: string` - A tool that allows the model to execute shell commands. + The unique ID of the multi-agent call. - - `type: "shell"` + - `output: array of BetaResponseOutputText` - The type of the shell tool. Always `shell`. + Text output returned by the multi-agent action. - - `"shell"` + - `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). + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - - `"direct"` + - `text: string` - - `"programmatic"` + The text output from the model. - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + - `type: "output_text"` - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + The type of the output text. Always `output_text`. - - `BetaLocalEnvironment object { type, skills }` + - `type: "multi_agent_call_output"` - - `BetaContainerReference object { container_id, type }` + The type of the multi-agent result. Always `multi_agent_call_output`. - - `Custom object { name, type, allowed_callers, 3 more }` + - `"multi_agent_call_output"` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `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`. + - `WebSearchCall object { id, action, status, 2 more }` - - `"custom"` + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `id: string` - The tool invocation context(s). + The unique ID of the web search tool call. - - `"direct"` + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - - `"programmatic"` + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). - - `defer_loading: optional boolean` + - `Search object { type, queries, query, sources }` - Whether this tool should be deferred and discovered via tool search. + Action type "search" - Performs a web search query. - - `description: optional string` + - `type: "search"` - Optional description of the custom tool, used to provide more context. + The action type. - - `format: optional object { type } or object { definition, syntax, type }` + - `"search"` - The input format for the custom tool. Default is unconstrained text. + - `queries: optional array of string` - - `Text object { type }` + The search queries. - Unconstrained free-form text. + - `query: optional string` - - `type: "text"` + The search query. - Unconstrained text format. Always `text`. + - `sources: optional array of object { type, url }` - - `"text"` + The sources used in the search. - - `Grammar object { definition, syntax, type }` + - `type: "url"` - A grammar defined by the user. + The type of source. Always `url`. - - `definition: string` + - `"url"` - The grammar definition. + - `url: string` - - `syntax: "lark" or "regex"` + The URL of the source. - The syntax of the grammar definition. One of `lark` or `regex`. + - `OpenPage object { type, url }` - - `"lark"` + Action type "open_page" - Opens a specific URL from search results. - - `"regex"` + - `type: "open_page"` - - `type: "grammar"` + The action type. - Grammar format. Always `grammar`. + - `"open_page"` - - `"grammar"` + - `url: optional string` - - `Namespace object { description, name, tools, type }` + The URL opened by the model. - Groups function/custom tools under a shared namespace. + - `FindInPage object { pattern, type, url }` - - `description: string` + Action type "find_in_page": Searches for a pattern within a loaded page. - A description of the namespace shown to the model. + - `pattern: string` - - `name: string` + The pattern or text to search for within the page. - The namespace name used in tool calls (for example, `crm`). + - `type: "find_in_page"` - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + The action type. - The function/custom tools available inside this namespace. + - `"find_in_page"` - - `Function object { name, type, allowed_callers, 5 more }` + - `url: string` - - `name: string` + The URL of the page searched for the pattern. - - `type: "function"` + - `status: "in_progress" or "searching" or "completed" or "failed"` - - `"function"` + The status of the web search tool call. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"in_progress"` - The tool invocation context(s). + - `"searching"` - - `"direct"` + - `"completed"` - - `"programmatic"` + - `"failed"` - - `defer_loading: optional boolean` + - `type: "web_search_call"` - Whether this function should be deferred and discovered via tool search. + The type of the web search tool call. Always `web_search_call`. - - `description: optional string` + - `"web_search_call"` - - `output_schema: optional map[unknown]` + - `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. + - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` - - `Custom object { name, type, allowed_callers, 3 more }` + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `id: string` - - `name: string` + The unique ID of the computer call. - The name of the custom tool, used to identify it in tool calls. + - `call_id: string` - - `type: "custom"` + An identifier used when responding to the tool call with output. - The type of the custom tool. Always `custom`. + - `pending_safety_checks: array of object { id, code, message }` - - `"custom"` + The pending safety checks for the computer call. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `id: string` - The tool invocation context(s). + The ID of the pending safety check. - - `"direct"` + - `code: optional string` - - `"programmatic"` + The type of the pending safety check. - - `defer_loading: optional boolean` + - `message: optional string` - Whether this tool should be deferred and discovered via tool search. + Details about the pending safety check. - - `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: "computer_call"` - - `type: "text"` + The type of the computer call. Always `computer_call`. - Unconstrained text format. Always `text`. + - `"computer_call"` - - `"text"` + - `action: optional BetaComputerAction` - - `Grammar object { definition, syntax, type }` + A click action. - A grammar defined by the user. + - `actions: optional BetaComputerActionList` - - `definition: string` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - 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"` + - `ComputerCallOutput object { id, call_id, output, 5 more }` - - `type: "grammar"` + - `id: string` - Grammar format. Always `grammar`. + The unique ID of the computer call tool output. - - `"grammar"` + - `call_id: string` - - `type: "namespace"` + The ID of the computer tool call that produced the output. - The type of the tool. Always `namespace`. + - `output: BetaResponseComputerToolCallOutputScreenshot` - - `"namespace"` + A computer screenshot image used with the computer use tool. - - `ToolSearch object { type, description, execution, parameters }` + - `status: "completed" or "incomplete" or "failed" or "in_progress"` - 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"` + - `"completed"` - The type of the tool. Always `tool_search`. + - `"incomplete"` - - `"tool_search"` + - `"failed"` - - `description: optional string` + - `"in_progress"` - Description shown to the model for a client-executed tool search tool. + - `type: "computer_call_output"` - - `execution: optional "server" or "client"` + The type of the computer tool call output. Always `computer_call_output`. - Whether tool search is executed by the server or by the client. + - `"computer_call_output"` - - `"server"` + - `acknowledged_safety_checks: optional array of object { id, code, message }` - - `"client"` + The safety checks reported by the API that have been acknowledged by the + developer. - - `parameters: optional unknown` + - `id: string` - Parameter schema for a client-executed tool search tool. + The ID of the pending safety check. - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + - `code: optional string` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The type of the pending safety check. - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `message: optional string` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + Details about the pending safety check. - - `"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"` + - `created_by: optional string` - - `search_context_size: optional "low" or "medium" or "high"` + The identifier of the actor that created the item. - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `Reasoning object { id, summary, type, 4 more }` - - `"low"` + 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). - - `"medium"` + - `id: string` - - `"high"` + The unique identifier of the reasoning content. - - `user_location: optional object { type, city, country, 2 more }` + - `summary: array of object { text, type }` - The user's location. + Reasoning summary content. - - `type: "approximate"` + - `text: string` - The type of location approximation. Always `approximate`. + A summary of the reasoning output from the model so far. - - `"approximate"` + - `type: "summary_text"` - - `city: optional string` + The type of the object. Always `summary_text`. - Free text input for the city of the user, e.g. `San Francisco`. + - `"summary_text"` + + - `type: "reasoning"` + + The type of the object. Always `reasoning`. - - `country: optional string` + - `"reasoning"` - 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`. + - `content: optional array of object { text, type }` - - `ApplyPatch object { type, allowed_callers }` + Reasoning text content. - Allows the assistant to create, delete, or update files using unified diffs. + - `text: string` - - `type: "apply_patch"` + The reasoning text from the model. - The type of the tool. Always `apply_patch`. + - `type: "reasoning_text"` - - `"apply_patch"` + The type of the reasoning text. Always `reasoning_text`. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"reasoning_text"` - The tool invocation context(s). + - `encrypted_content: optional string` - - `"direct"` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - - `"programmatic"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `type: "additional_tools"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The type of the item. Always `additional_tools`. + - `"in_progress"` - - `"additional_tools"` + - `"completed"` - - `agent: optional object { agent_name }` + - `"incomplete"` - The agent that produced this item. + - `Program object { id, call_id, code, 3 more }` - - `agent_name: string` + - `id: string` - The canonical name of the agent that produced this item. + The unique ID of the program item. - - `Compaction object { id, encrypted_content, type, 2 more }` + - `call_id: string` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + The stable call ID of the program item. - - `id: string` + - `code: string` - The unique ID of the compaction item. + The JavaScript source executed by programmatic tool calling. - - `encrypted_content: string` + - `fingerprint: string` - The encrypted content that was produced by compaction. + Opaque program replay fingerprint that must be round-tripped. - - `type: "compaction"` + - `type: "program"` - The type of the item. Always `compaction`. + The type of the item. Always `program`. - - `"compaction"` + - `"program"` - `agent: optional object { agent_name }` @@ -96605,39 +95348,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 the 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 item. - `"completed"` - - `"generating"` - - - `"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 }` @@ -96647,58 +95384,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"` @@ -96706,1031 +95462,1046 @@ 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 { id, action, call_id, 6 more }` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - A tool call that executes one or more shell commands in a managed environment. + - `key: string` - - `id: string` + The key to compare against the value. - The unique ID of the shell tool call. Populated when this item is returned via API. + - `type: "eq" or "ne" or "gt" or 5 more` - - `action: object { commands, max_output_length, timeout_ms }` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The shell commands and limits that describe how to run the 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 - - `commands: array of string` + - `"eq"` - - `max_output_length: number` + - `"ne"` - Optional maximum number of characters to return from each command. + - `"gt"` - - `timeout_ms: number` + - `"gte"` - Optional timeout in milliseconds for the commands. + - `"lt"` - - `call_id: string` + - `"lte"` - The unique ID of the shell tool call generated by the model. + - `"in"` - - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` + - `"nin"` - Represents the use of a local environment to perform shell actions. + - `value: string or number or boolean or array of string or number` - - `BetaResponseLocalEnvironment object { type }` + The value to compare against the attribute key; supports string, number, or boolean types. - Represents the use of a local environment to perform shell actions. + - `string` - - `type: "local"` + - `number` - The environment type. Always `local`. + - `boolean` - - `"local"` + - `array of string or number` - - `BetaResponseContainerReference object { container_id, type }` + - `string` - Represents a container created with /v1/containers. + - `number` - - `container_id: string` + - `unknown` - - `type: "container_reference"` + - `type: "and" or "or"` - The environment type. Always `container_reference`. + Type of operation: `and` or `or`. - - `"container_reference"` + - `"and"` - - `status: "in_progress" or "completed" or "incomplete"` + - `"or"` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `max_num_results: optional number` - - `"in_progress"` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `"completed"` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `"incomplete"` + Ranking options for search. - - `type: "shell_call"` + - `hybrid_search: optional object { embedding_weight, text_weight }` - The type of the item. Always `shell_call`. + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `"shell_call"` + - `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"` - - `caller: optional object { type } or object { caller_id, type }` + The ranker to use for the file search. - The execution context that produced this tool call. + - `"auto"` - - `Direct object { type }` + - `"default-2024-11-15"` - - `type: "direct"` + - `score_threshold: optional number` - - `"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. - - `Program object { caller_id, type }` + - `Computer object { type }` - - `caller_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 call ID of the program item that produced this tool call. + - `type: "computer"` - - `type: "program"` + The type of the computer tool. Always `computer`. - - `"program"` + - `"computer"` - - `created_by: optional string` + - `ComputerUsePreview object { display_height, display_width, environment, type }` - The ID of the entity that created 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). - - `ShellCallOutput object { id, call_id, max_output_length, 6 more }` + - `display_height: number` - The output of a shell tool call that was emitted. + The height of the computer display. - - `id: string` + - `display_width: number` - The unique ID of the shell call output. Populated when this item is returned via API. + The width of the computer display. - - `call_id: string` + - `environment: "windows" or "mac" or "linux" or 2 more` - The unique ID of the shell tool call generated by the model. + The type of computer environment to control. - - `max_output_length: number` + - `"windows"` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `"mac"` - - `output: array of object { outcome, stderr, stdout, created_by }` + - `"linux"` - An array of shell call output contents + - `"ubuntu"` - - `outcome: object { type } or object { exit_code, type }` + - `"browser"` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + - `type: "computer_use_preview"` - - `Timeout object { type }` + The type of the computer use tool. Always `computer_use_preview`. - Indicates that the shell call exceeded its configured time limit. + - `"computer_use_preview"` - - `type: "timeout"` + - `WebSearch object { type, filters, search_context_size, user_location }` - The outcome type. Always `timeout`. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - - `"timeout"` + - `type: "web_search" or "web_search_2025_08_26"` - - `Exit object { exit_code, type }` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - Indicates that the shell commands finished and returned an exit code. + - `"web_search"` - - `exit_code: number` + - `"web_search_2025_08_26"` - Exit code from the shell process. + - `filters: optional object { allowed_domains }` - - `type: "exit"` + Filters for the search. - The outcome type. Always `exit`. + - `allowed_domains: optional array of string` - - `"exit"` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `stderr: string` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - The standard error output that was captured. + - `search_context_size: optional "low" or "medium" or "high"` - - `stdout: string` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - The standard output that was captured. + - `"low"` - - `created_by: optional string` + - `"medium"` - The identifier of the actor that created the item. + - `"high"` - - `status: "in_progress" or "completed" or "incomplete"` + - `user_location: optional object { city, country, region, 2 more }` - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + The approximate location of the user. - - `"in_progress"` + - `city: optional string` - - `"completed"` + Free text input for the city of the user, e.g. `San Francisco`. - - `"incomplete"` + - `country: optional string` - - `type: "shell_call_output"` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The type of the shell call output. Always `shell_call_output`. + - `region: optional string` - - `"shell_call_output"` + Free text input for the region of the user, e.g. `California`. - - `agent: optional object { agent_name }` + - `timezone: optional string` - The agent that produced this item. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `agent_name: string` + - `type: optional "approximate"` - The canonical name of the agent that produced this item. + The type of location approximation. Always `approximate`. - - `caller: optional object { type } or object { caller_id, type }` + - `"approximate"` - The execution context that produced this tool call. + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `Direct object { type }` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - - `type: "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"` - - `"program"` + The tool invocation context(s). - - `created_by: optional string` + - `"direct"` - The identifier of the actor that created the item. + - `"programmatic"` - - `ApplyPatchCall object { id, call_id, operation, 5 more }` + - `allowed_tools: optional array of string or object { read_only, tool_names }` - A tool call that applies file diffs by creating, deleting, or updating files. + List of allowed tool names or a filter object. - - `id: string` + - `McpAllowedTools = array of string` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + A string array of allowed tool names - - `call_id: string` + - `McpToolFilter object { read_only, tool_names }` - The unique ID of the apply patch tool call generated by the model. + A filter object to specify which tools are allowed. - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + - `read_only: optional boolean` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + 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. - - `CreateFile object { diff, path, type }` + - `tool_names: optional array of string` - Instruction describing how to create a file via the apply_patch tool. + List of allowed tool names. - - `diff: string` + - `authorization: optional string` - Diff to apply. + 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. - - `path: string` + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - Path of the file to create. + 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: "create_file"` + Currently supported `connector_id` values are: - Create a new file with the provided diff. + - 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` - - `"create_file"` + - `"connector_dropbox"` - - `DeleteFile object { path, type }` + - `"connector_gmail"` - Instruction describing how to delete a file via the apply_patch tool. + - `"connector_googlecalendar"` - - `path: string` + - `"connector_googledrive"` - Path of the file to delete. + - `"connector_microsoftteams"` - - `type: "delete_file"` + - `"connector_outlookcalendar"` - Delete the specified file. + - `"connector_outlookemail"` - - `"delete_file"` + - `"connector_sharepoint"` - - `UpdateFile object { diff, path, type }` + - `defer_loading: optional boolean` - Instruction describing how to update a file via the apply_patch tool. + Whether this MCP tool is deferred and discovered via tool search. - - `diff: string` + - `headers: optional map[string]` - Diff to apply. + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `path: string` + - `require_approval: optional object { always, never } or "always" or "never"` - Path of the file to update. + Specify which of the MCP server's tools require approval. - - `type: "update_file"` + - `McpToolApprovalFilter object { always, never }` - Update an existing file with the provided diff. + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `"update_file"` + - `always: optional object { read_only, tool_names }` - - `status: "in_progress" or "completed"` + A filter object to specify which tools are allowed. - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `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` - - `type: "apply_patch_call"` + List of allowed tool names. - The type of the item. Always `apply_patch_call`. + - `never: optional object { read_only, tool_names }` - - `"apply_patch_call"` + 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 }` + - `McpToolApprovalSetting = "always" or "never"` - The execution context 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. - - `Direct object { type }` + - `"always"` - - `type: "direct"` + - `"never"` - - `"direct"` + - `server_description: optional string` - - `Program object { caller_id, type }` + Optional description of the MCP server, used to provide more context. - - `caller_id: string` + - `server_url: optional string` - The call ID of the program item that produced this tool call. + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `type: "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. - - `created_by: optional string` + - `CodeInterpreter object { container, type, allowed_callers }` - The ID of the entity that created this tool call. + A tool that runs Python code to help generate a response to a prompt. - - `ApplyPatchCallOutput object { id, call_id, status, 5 more }` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - The output emitted by an apply patch 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. - - `id: string` + - `string` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + The container ID. - - `call_id: string` + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - The unique ID of the apply patch tool call generated by the model. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `status: "completed" or "failed"` + - `type: "auto"` - The status of the apply patch tool call output. One of `completed` or `failed`. + Always `auto`. - - `"completed"` + - `"auto"` - - `"failed"` + - `file_ids: optional array of string` - - `type: "apply_patch_call_output"` + An optional list of uploaded files to make available to your code. - The type of the item. Always `apply_patch_call_output`. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `"apply_patch_call_output"` + The memory limit for the code interpreter container. - - `agent: optional object { agent_name }` + - `"1g"` - The agent that produced this item. + - `"4g"` - - `agent_name: string` + - `"16g"` - The canonical name of the agent that produced this item. + - `"64g"` - - `caller: optional object { type } or object { caller_id, type }` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - The execution context that produced this tool call. + Network access policy for the container. - - `Direct object { type }` + - `BetaContainerNetworkPolicyDisabled object { type }` - - `type: "direct"` + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `"direct"` + - `type: "code_interpreter"` - - `Program object { caller_id, type }` + The type of the code interpreter tool. Always `code_interpreter`. - - `caller_id: string` + - `"code_interpreter"` - 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 ID of the entity that created this tool call output. + - `ProgrammaticToolCalling object { type }` - - `output: optional string` + - `type: "programmatic_tool_calling"` - Optional textual output returned by the apply patch tool. + The type of the tool. Always `programmatic_tool_calling`. - - `McpCall object { id, arguments, name, 7 more }` + - `"programmatic_tool_calling"` - An invocation of a tool on an MCP server. + - `ImageGeneration object { type, action, background, 9 more }` - - `id: string` + A tool that generates images using the GPT image models. - The unique ID of the tool call. + - `type: "image_generation"` - - `arguments: string` + The type of the image generation tool. Always `image_generation`. - A JSON string of the arguments passed to the tool. + - `"image_generation"` - - `name: string` + - `action: optional "generate" or "edit" or "auto"` - The name of the tool that was run. + Whether to generate a new image or edit an existing image. Default: `auto`. - - `server_label: string` + - `"generate"` - The label of the MCP server running the tool. + - `"edit"` - - `type: "mcp_call"` + - `"auto"` - The type of the item. Always `mcp_call`. + - `background: optional "transparent" or "opaque" or "auto"` - - `"mcp_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"` - - `approval_request_id: 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`. - 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. + - `"high"` - - `error: optional string` + - `"low"` - The error from the tool call, if any. + - `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). - The output from the tool call. + - `file_id: optional string` - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + File ID for the mask image. - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `image_url: optional string` - - `"in_progress"` + Base64-encoded mask image. - - `"completed"` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `"incomplete"` + The image generation model to use. Default: `gpt-image-1`. - - `"calling"` + - `string` - - `"failed"` + - `"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. + - `"gpt-image-1"` - - `id: string` + - `"gpt-image-1-mini"` - The unique ID of the list. + - `"gpt-image-1.5"` - - `server_label: string` + - `moderation: optional "auto" or "low"` - The label of the MCP server. + Moderation level for the generated image. Default: `auto`. - - `tools: array of object { input_schema, name, annotations, description }` + - `"auto"` - The tools available on the server. + - `"low"` - - `input_schema: unknown` + - `output_compression: optional number` - The JSON schema describing the tool's input. + Compression level for the output image. Default: 100. - - `name: string` + - `output_format: optional "png" or "webp" or "jpeg"` - The name of the tool. + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `annotations: optional unknown` + - `"png"` - Additional annotations about the tool. + - `"webp"` - - `description: optional string` + - `"jpeg"` - The description of the tool. + - `partial_images: optional number` - - `type: "mcp_list_tools"` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - The type of the item. Always `mcp_list_tools`. + - `quality: optional "low" or "medium" or "high" or "auto"` - - `"mcp_list_tools"` + 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"` - - `error: optional string` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - Error message if the server could not 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`. - - `McpApprovalRequest object { id, arguments, name, 3 more }` + - `string` - A request for human approval of a tool invocation. + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `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 unique ID of the approval request. + - `"1024x1024"` - - `arguments: string` + - `"1024x1536"` - A JSON string of arguments for the tool. + - `"1536x1024"` - - `name: string` + - `"auto"` - The name of the tool to run. + - `LocalShell object { type }` - - `server_label: string` + A tool that allows the model to execute shell commands in a local environment. - The label of the MCP server making the request. + - `type: "local_shell"` - - `type: "mcp_approval_request"` + The type of the local shell tool. Always `local_shell`. - The type of the item. Always `mcp_approval_request`. + - `"local_shell"` - - `"mcp_approval_request"` + - `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"` - - `McpApprovalResponse object { id, approval_request_id, approve, 3 more }` + - `allowed_callers: optional array of "direct" or "programmatic"` - A response to an MCP approval request. + The tool invocation context(s). - - `id: string` + - `"direct"` - The unique ID of the approval response + - `"programmatic"` - - `approval_request_id: string` + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - The ID of the approval request being answered. + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - - `approve: boolean` + - `BetaLocalEnvironment object { type, skills }` - Whether the request was approved. + - `BetaContainerReference object { container_id, type }` - - `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` - - `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"` - - `reason: optional string` + - `allowed_callers: optional array of "direct" or "programmatic"` - Optional reason for the decision. + The tool invocation context(s). - - `CustomToolCall object { call_id, input, name, 5 more }` + - `"direct"` - A call to a custom tool created by the model. + - `"programmatic"` - - `call_id: string` + - `defer_loading: optional boolean` - An identifier used to map this custom tool call to a tool call output. + Whether this tool should be deferred and discovered via tool search. - - `input: string` + - `description: optional string` - The input for the custom tool call generated by the model. + Optional description of the custom tool, used to provide more context. - - `name: string` + - `format: optional object { type } or object { definition, syntax, type }` - The name of the custom tool being called. + The input format for the custom tool. Default is unconstrained text. - - `type: "custom_tool_call"` + - `Text object { type }` - The type of the custom tool call. Always `custom_tool_call`. + Unconstrained free-form text. - - `"custom_tool_call"` + - `type: "text"` - - `id: optional string` + Unconstrained text format. Always `text`. - The unique ID of the custom tool call in the OpenAI platform. + - `"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. + - `Namespace object { description, name, tools, type }` - - `type: "program"` + Groups function/custom tools under a shared namespace. - - `"program"` + - `description: string` - - `namespace: optional string` + A description of the namespace shown to the model. - The namespace of the custom tool being called. + - `name: string` - - `CustomToolCallOutput object { id, call_id, output, 5 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 the custom tool call output item. + The function/custom tools available inside this namespace. - - `call_id: string` + - `Function object { name, type, allowed_callers, 5 more }` - 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` + - `type: "function"` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `"function"` - - `StringOutput = string` + - `allowed_callers: optional array of "direct" or "programmatic"` - A string of the output of the custom tool call. + The tool invocation context(s). - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `"direct"` - Text, image, or file output of the custom tool call. + - `"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. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `description: optional string` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `output_schema: optional map[unknown]` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - A file input to the model. + - `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: "custom_tool_call_output"` + The name of the custom tool, used to identify it in tool calls. - The type of the custom tool call output. Always `custom_tool_call_output`. + - `type: "custom"` - - `"custom_tool_call_output"` + 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"` + + Unconstrained text format. Always `text`. - The caller type. Always `program`. + - `"text"` - - `"program"` + - `Grammar object { definition, syntax, type }` - - `created_by: optional string` + A grammar defined by the user. - The identifier of the actor that created the item. + - `definition: string` - - `parallel_tool_calls: boolean` + The grammar definition. - Whether to allow the model to run tool calls in parallel. + - `syntax: "lark" or "regex"` - - `temperature: number` + The syntax of the grammar definition. One of `lark` or `regex`. - 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. + - `"lark"` - - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` + - `"regex"` - 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: "grammar"` - - `BetaToolChoiceOptions = "none" or "auto" or "required"` + Grammar format. Always `grammar`. - Controls which (if any) tool is called by the model. + - `"grammar"` - `none` means the model will not call any tool and instead generates a message. + - `type: "namespace"` - `auto` means the model can pick between generating a message or calling one or - more tools. + The type of the tool. Always `namespace`. - `required` means the model must call one or more tools. + - `"namespace"` - - `"none"` + - `ToolSearch object { type, description, execution, parameters }` - - `"auto"` + Hosted or BYOT tool search configuration for deferred tools. - - `"required"` + - `type: "tool_search"` - - `BetaToolChoiceAllowed object { mode, tools, type }` + The type of the tool. Always `tool_search`. - Constrains the tools available to the model to a pre-defined set. + - `"tool_search"` - - `mode: "auto" or "required"` + - `description: optional string` - Constrains the tools available to the model to a pre-defined set. + Description shown to the model for a client-executed tool search tool. - `auto` allows the model to pick from among the allowed tools and generate a - message. + - `execution: optional "server" or "client"` - `required` requires the model to call one or more of the allowed tools. + Whether tool search is executed by the server or by the client. - - `"auto"` + - `"server"` - - `"required"` + - `"client"` - - `tools: array of map[unknown]` + - `parameters: optional unknown` - A list of tool definitions that the model should be allowed to call. + Parameter schema for a client-executed tool search tool. - For the Responses API, the list of tool definitions might look like: + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + 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: "allowed_tools"` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - Allowed tool configuration type. Always `allowed_tools`. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `"allowed_tools"` + - `"web_search_preview"` - - `BetaToolChoiceTypes object { type }` + - `"web_search_preview_2025_03_11"` - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + - `search_content_types: optional array of "text" or "image"` - - `type: "file_search" or "web_search_preview" or "computer" or 5 more` + - `"text"` - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + - `"image"` - Allowed values are: + - `search_context_size: optional "low" or "medium" or "high"` - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + 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"` + - `"low"` - - `"web_search_preview"` + - `"medium"` - - `"computer"` + - `"high"` - - `"computer_use_preview"` + - `user_location: optional object { type, city, country, 2 more }` - - `"computer_use"` + The user's location. - - `"web_search_preview_2025_03_11"` + - `type: "approximate"` - - `"image_generation"` + The type of location approximation. Always `approximate`. - - `"code_interpreter"` + - `"approximate"` - - `BetaToolChoiceFunction object { name, type }` + - `city: optional string` - Use this option to force the model to call a specific function. + Free text input for the city of the user, e.g. `San Francisco`. - - `name: string` + - `country: optional string` - The name of the function to call. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `type: "function"` + - `region: optional string` - For function calling, the type is always `function`. + Free text input for the region of the user, e.g. `California`. - - `"function"` + - `timezone: optional string` - - `BetaToolChoiceMcp object { server_label, type, name }` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - Use this option to force the model to call a specific tool on a remote MCP server. + - `ApplyPatch object { type, allowed_callers }` - - `server_label: string` + Allows the assistant to create, delete, or update files using unified diffs. - The label of the MCP server to use. + - `type: "apply_patch"` - - `type: "mcp"` + The type of the tool. Always `apply_patch`. - For MCP tools, the type is always `mcp`. + - `"apply_patch"` - - `"mcp"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `name: optional string` + The tool invocation context(s). - The name of the tool to call on the server. + - `"direct"` - - `BetaToolChoiceCustom object { name, type }` + - `"programmatic"` - Use this option to force the model to call a specific custom tool. + - `type: "tool_search_output"` - - `name: string` + The type of the item. Always `tool_search_output`. - The name of the custom tool to call. + - `"tool_search_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` - - `BetaSpecificProgrammaticToolCallingParam object { type }` + The canonical name of the agent that produced this item. - - `type: "programmatic_tool_calling"` + - `created_by: optional string` - The tool to call. Always `programmatic_tool_calling`. + The identifier of the actor that created the item. - - `"programmatic_tool_calling"` + - `AdditionalTools object { id, role, tools, 2 more }` - - `BetaToolChoiceApplyPatch object { type }` + - `id: string` - Forces the model to call the apply_patch tool when executing a tool call. + The unique ID of the additional tools item. - - `type: "apply_patch"` + - `role: "unknown" or "user" or "assistant" or 5 more` - The tool to call. Always `apply_patch`. + The role that provided the additional tools. - - `"apply_patch"` + - `"unknown"` - - `BetaToolChoiceShell object { type }` + - `"user"` - Forces the model to call the shell tool when a tool call is required. + - `"assistant"` - - `type: "shell"` + - `"system"` - The tool to call. Always `shell`. + - `"critic"` - - `"shell"` + - `"discriminator"` - - `tools: 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. + - `"tool"` - 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](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/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](https://platform.openai.com/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](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. + The additional tool definitions made available at this item. - `Function object { name, parameters, strict, 5 more }` @@ -97993,7 +96764,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-web-search). + [web search tool](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -98053,7 +96824,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -98105,7 +96876,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -98297,19 +97068,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `background: optional "transparent" or "opaque" or "auto"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. - - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. - - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - `"transparent"` @@ -98338,13 +97098,13 @@ curl -X POST https://api.openai.com/v1/responses/compact \ Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `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-2" or 3 more` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` The image generation model to use. Default: `gpt-image-1`. @@ -98352,14 +97112,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"gpt-image-1-mini"` - - `"gpt-image-2"` - - - `"gpt-image-2-2026-04-21"` - - `"gpt-image-1.5"` - - `"chatgpt-image-latest"` - - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -98456,7 +97210,121 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + 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` @@ -98464,2668 +97332,3447 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "custom"` - The type of the custom tool. Always `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` + + 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 + + - `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. + + - `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` + + Exit code from the shell process. + + - `type: "exit"` + + The outcome type. Always `exit`. + + - `"exit"` + + - `stderr: string` + + The standard error output that was captured. + + - `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"` + + - `type: "shell_call_output"` + + The type of the shell call output. Always `shell_call_output`. + + - `"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"` + + - `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"` - - `"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. + - `"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"` + - `"program"` - Unconstrained text format. Always `text`. + - `created_by: optional string` - - `"text"` + The ID of the entity that created this tool call. - - `Grammar object { definition, syntax, type }` + - `ApplyPatchCallOutput object { id, call_id, status, 5 more }` - A grammar defined by the user. + The output emitted by an apply patch tool call. - - `definition: string` + - `id: string` - The grammar definition. + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `syntax: "lark" or "regex"` + - `call_id: string` - The syntax of the grammar definition. One of `lark` or `regex`. + The unique ID of the apply patch tool call generated by the model. - - `"lark"` + - `status: "completed" or "failed"` - - `"regex"` + The status of the apply patch tool call output. One of `completed` or `failed`. - - `type: "grammar"` + - `"completed"` - Grammar format. Always `grammar`. + - `"failed"` - - `"grammar"` + - `type: "apply_patch_call_output"` - - `Namespace object { description, name, tools, type }` + The type of the item. Always `apply_patch_call_output`. - Groups function/custom tools under a shared namespace. + - `"apply_patch_call_output"` - - `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 }` + - `caller: optional object { type } or object { caller_id, type }` - The function/custom tools available inside this namespace. + The execution context that produced this tool call. - - `Function object { name, type, allowed_callers, 5 more }` + - `Direct object { type }` - - `name: string` + - `type: "direct"` - - `type: "function"` + - `"direct"` - - `"function"` + - `Program object { caller_id, type }` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `caller_id: string` - The tool invocation context(s). + The call ID of the program item that produced this tool call. - - `"direct"` + - `type: "program"` - - `"programmatic"` + - `"program"` - - `defer_loading: optional boolean` + - `created_by: optional string` - Whether this function should be deferred and discovered via tool search. + The ID of the entity that created this tool call output. - - `description: optional string` + - `output: optional string` - - `output_schema: optional map[unknown]` + Optional textual output returned by the apply patch tool. - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `McpCall object { id, arguments, name, 7 more }` - - `parameters: optional unknown` + An invocation of a tool on an MCP server. - - `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 tool call. - - `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](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A JSON string of the arguments passed to the tool. - `name: string` - The name of the custom tool, used to identify it in tool calls. - - - `type: "custom"` + The name of the tool that was run. - The type of the custom tool. Always `custom`. + - `server_label: string` - - `"custom"` + 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 }` - - `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. + - `approval_request_id: optional string` - - `format: optional object { type } or object { definition, syntax, 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 input format for the custom tool. Default is unconstrained text. + - `error: optional string` - - `Text object { type }` + The error from the tool call, if any. - Unconstrained free-form text. + - `output: optional string` - - `type: "text"` + The output from the tool call. - Unconstrained text format. Always `text`. + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - - `"text"` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `Grammar object { definition, syntax, type }` + - `"in_progress"` - A grammar defined by the user. + - `"completed"` - - `definition: string` + - `"incomplete"` - The grammar definition. + - `"calling"` - - `syntax: "lark" or "regex"` + - `"failed"` - The syntax of the grammar definition. One of `lark` or `regex`. + - `McpListTools object { id, server_label, tools, 3 more }` - - `"lark"` + A list of tools available on an MCP server. - - `"regex"` + - `id: string` - - `type: "grammar"` + The unique ID of the list. - Grammar format. Always `grammar`. + - `server_label: string` - - `"grammar"` + The label of the MCP server. - - `type: "namespace"` + - `tools: array of object { input_schema, name, annotations, description }` - The type of the tool. Always `namespace`. + The tools available on the server. - - `"namespace"` + - `input_schema: unknown` - - `ToolSearch object { type, description, execution, parameters }` + The JSON schema describing the tool's input. - Hosted or BYOT tool search configuration for deferred tools. + - `name: string` - - `type: "tool_search"` + The name of the tool. - The type of the tool. Always `tool_search`. + - `annotations: optional unknown` - - `"tool_search"` + Additional annotations about the tool. - `description: optional string` - Description shown to the model for a client-executed tool search tool. - - - `execution: optional "server" or "client"` + The description of the tool. - Whether tool search is executed by the server or by the client. + - `type: "mcp_list_tools"` - - `"server"` + The type of the item. Always `mcp_list_tools`. - - `"client"` + - `"mcp_list_tools"` - - `parameters: optional unknown` + - `agent: optional object { agent_name }` - Parameter schema for a client-executed tool search tool. + The agent that produced this item. - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + - `agent_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 canonical name of the agent that produced this item. - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `error: optional string` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + Error message if the server could not list tools. - - `"web_search_preview"` + - `McpApprovalRequest object { id, arguments, name, 3 more }` - - `"web_search_preview_2025_03_11"` + A request for human approval of a tool invocation. - - `search_content_types: optional array of "text" or "image"` + - `id: string` - - `"text"` + The unique ID of the approval request. - - `"image"` + - `arguments: string` - - `search_context_size: optional "low" or "medium" or "high"` + A JSON string of arguments for the tool. - 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. + - `name: string` - - `"low"` + The name of the tool to run. - - `"medium"` + - `server_label: string` - - `"high"` + The label of the MCP server making the request. - - `user_location: optional object { type, city, country, 2 more }` + - `type: "mcp_approval_request"` - The user's location. + The type of the item. Always `mcp_approval_request`. - - `type: "approximate"` + - `"mcp_approval_request"` - 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` + - `McpApprovalResponse object { id, approval_request_id, approve, 3 more }` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + A response to an MCP approval request. - - `region: optional string` + - `id: string` - Free text input for the region of the user, e.g. `California`. + The unique ID of the approval response - - `timezone: optional string` + - `approval_request_id: string` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The ID of the approval request being answered. - - `ApplyPatch object { type, allowed_callers }` + - `approve: boolean` - Allows the assistant to create, delete, or update files using unified diffs. + Whether the request was approved. - - `type: "apply_patch"` + - `type: "mcp_approval_response"` - The type of the tool. Always `apply_patch`. + The type of the item. Always `mcp_approval_response`. - - `"apply_patch"` + - `"mcp_approval_response"` - - `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. - - `top_p: number` + - `reason: 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. + Optional reason for the decision. - We generally recommend altering this or `temperature` but not both. + - `CustomToolCall object { call_id, input, name, 5 more }` - - `background: optional boolean` + A call to a custom tool created by the model. - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + - `call_id: string` - - `completed_at: optional number` + An identifier used to map this custom tool call to a tool call output. - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + - `input: string` - - `conversation: optional object { id }` + The input for the custom tool call generated by the model. - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + - `name: string` - - `id: string` + The name of the custom tool being called. - The unique ID of the conversation that this response was associated with. + - `type: "custom_tool_call"` - - `max_output_tokens: optional number` + The type of the custom tool call. Always `custom_tool_call`. - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + - `"custom_tool_call"` - - `max_tool_calls: optional number` + - `id: optional 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 unique ID of the custom tool call in the OpenAI platform. - - `moderation: optional object { input, output }` + - `agent: optional object { agent_name }` - Moderation results for the response input and output, if moderated completions were requested. + The agent that produced this item. - - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + - `agent_name: string` - Moderation for the response input. + The canonical name of the agent that produced this item. - - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` + - `caller: optional object { type } or object { caller_id, type }` - A moderation result produced for the response input or output. + The execution context that produced this tool call. - - `categories: map[boolean]` + - `Direct object { type }` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `type: "direct"` - - `category_applied_input_types: map[array of "text" or "image"]` + - `"direct"` - Which modalities of input are reflected by the score for each category. + - `Program object { caller_id, type }` - - `"text"` + - `caller_id: string` - - `"image"` + The call ID of the program item that produced this tool call. - - `category_scores: map[number]` + - `type: "program"` - A dictionary of moderation categories to scores. + - `"program"` - - `flagged: boolean` + - `namespace: optional string` - A boolean indicating whether the content was flagged by any category. + The namespace of the custom tool being called. - - `model: string` + - `CustomToolCallOutput object { id, call_id, output, 5 more }` - The moderation model that produced this result. + - `id: string` - - `type: "moderation_result"` + The unique ID of the custom tool call output item. - The object type, which was always `moderation_result` for successful moderation results. + - `call_id: string` - - `"moderation_result"` + The call ID, used to map this custom tool call output to a custom tool call. - - `Error object { code, message, type }` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - An error produced while attempting moderation for the response input or output. + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `code: string` + - `StringOutput = string` - The error code. + A string of the output of the custom tool call. - - `message: string` + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - The error message. + Text, image, or file output of the custom tool call. - - `type: "error"` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - The object type, which was always `error` for moderation failures. + A text input to the model. - - `"error"` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - Moderation for the response output. + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` + A file input to the model. - A moderation result produced for the response input or output. + - `status: "in_progress" or "completed" or "incomplete"` - - `categories: map[boolean]` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `"in_progress"` - - `category_applied_input_types: map[array of "text" or "image"]` + - `"completed"` - Which modalities of input are reflected by the score for each category. + - `"incomplete"` - - `"text"` + - `type: "custom_tool_call_output"` - - `"image"` + The type of the custom tool call output. Always `custom_tool_call_output`. - - `category_scores: map[number]` + - `"custom_tool_call_output"` - A dictionary of moderation categories to scores. + - `agent: optional object { agent_name }` - - `flagged: boolean` + The agent that produced this item. - A boolean indicating whether the content was flagged by any category. + - `agent_name: string` - - `model: string` + The canonical name of the agent that produced this item. - The moderation model that produced this result. + - `caller: optional object { type } or object { caller_id, type }` - - `type: "moderation_result"` + The execution context that produced this tool call. - The object type, which was always `moderation_result` for successful moderation results. + - `Direct object { type }` - - `"moderation_result"` + - `type: "direct"` - - `Error object { code, message, type }` + The caller type. Always `direct`. - An error produced while attempting moderation for the response input or output. + - `"direct"` - - `code: string` + - `Program object { caller_id, type }` - The error code. + - `caller_id: string` - - `message: string` + The call ID of the program item that produced this tool call. - The error message. + - `type: "program"` - - `type: "error"` + The caller type. Always `program`. - The object type, which was always `error` for moderation failures. + - `"program"` - - `"error"` + - `created_by: optional string` - - `previous_response_id: optional string` + The identifier of the actor that created the item. - The unique ID of the previous response to the model. Use this to - create multi-turn conversations. Learn more about - [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + - `parallel_tool_calls: boolean` - - `prompt: optional BetaResponsePrompt` + Whether to allow the model to run tool calls in parallel. - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + - `temperature: number` - - `id: string` + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + We generally recommend altering this or `top_p` but not both. - The unique identifier of the prompt template to use. + - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` - - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` + 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. - 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. + - `BetaToolChoiceOptions = "none" or "auto" or "required"` - - `string` + Controls which (if any) tool is called by the model. - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + `none` means the model will not call any tool and instead generates a message. - A text input to the model. + `auto` means the model can pick between generating a message or calling one or + more tools. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + `required` means the model must call one or more tools. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `"none"` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `"auto"` - A file input to the model. + - `"required"` - - `version: optional string` + - `BetaToolChoiceAllowed object { mode, tools, type }` - Optional version of the prompt template. + Constrains the tools available to the model to a pre-defined set. - - `prompt_cache_key: optional string` + - `mode: "auto" or "required"` - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + Constrains the tools available to the model to a pre-defined set. - - `prompt_cache_options: optional object { mode, ttl }` + `auto` allows the model to pick from among the allowed tools and generate a + message. - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + `required` requires the model to call one or more of the allowed tools. - - `mode: "implicit" or "explicit"` + - `"auto"` - Whether implicit prompt-cache breakpoints were enabled. + - `"required"` - - `"implicit"` + - `tools: array of map[unknown]` - - `"explicit"` + A list of tool definitions that the model should be allowed to call. - - `ttl: "30m"` + For the Responses API, the list of tool definitions might look like: - The minimum lifetime applied to each cache breakpoint. + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - - `"30m"` + - `type: "allowed_tools"` - - `prompt_cache_retention: optional "in_memory" or "24h"` + Allowed tool configuration type. Always `allowed_tools`. - Deprecated. Use `prompt_cache_options.ttl` instead. + - `"allowed_tools"` - 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](https://platform.openai.com/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. + - `BetaToolChoiceTypes object { type }` - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](/docs/guides/tools). - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `type: "file_search" or "web_search_preview" or "computer" or 5 more` - - `"in_memory"` + The type of hosted tool the model should to use. Learn more about + [built-in tools](/docs/guides/tools). - - `"24h"` + Allowed values are: - - `reasoning: optional object { context, effort, generate_summary, 2 more }` + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - **gpt-5 and o-series models only** + - `"file_search"` - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + - `"web_search_preview"` - - `context: optional "auto" or "current_turn" or "all_turns"` + - `"computer"` - Controls which reasoning items are rendered back to the model on later turns. - When returned on a response, this is the effective reasoning context mode - used for the response. + - `"computer_use_preview"` - - `"auto"` + - `"computer_use"` - - `"current_turn"` + - `"web_search_preview_2025_03_11"` - - `"all_turns"` + - `"image_generation"` - - `effort: optional "none" or "minimal" or "low" or 4 more` + - `"code_interpreter"` - 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. + - `BetaToolChoiceFunction object { name, type }` - - `"none"` + Use this option to force the model to call a specific function. - - `"minimal"` + - `name: string` - - `"low"` + The name of the function to call. - - `"medium"` + - `type: "function"` - - `"high"` + For function calling, the type is always `function`. - - `"xhigh"` + - `"function"` - - `"max"` + - `BetaToolChoiceMcp object { server_label, type, name }` - - `generate_summary: optional "auto" or "concise" or "detailed"` + Use this option to force the model to call a specific tool on a remote MCP server. - **Deprecated:** use `summary` instead. + - `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`. + The label of the MCP server to use. - - `"auto"` + - `type: "mcp"` - - `"concise"` + For MCP tools, the type is always `mcp`. - - `"detailed"` + - `"mcp"` - - `mode: optional string or "standard" or "pro"` + - `name: optional string` - Controls the reasoning execution mode for the request. + The name of the tool to call on the server. - When returned on a response, this is the effective execution mode. + - `BetaToolChoiceCustom object { name, type }` - - `string` + Use this option to force the model to call a specific custom tool. - - `"standard" or "pro"` + - `name: string` - Controls the reasoning execution mode for the request. + The name of the custom tool to call. - When returned on a response, this is the effective execution mode. + - `type: "custom"` - - `"standard"` + For custom tool calling, the type is always `custom`. - - `"pro"` + - `"custom"` - - `summary: optional "auto" or "concise" or "detailed"` + - `BetaSpecificProgrammaticToolCallingParam object { 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`. + - `type: "programmatic_tool_calling"` - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + The tool to call. Always `programmatic_tool_calling`. - - `"auto"` + - `"programmatic_tool_calling"` - - `"concise"` + - `BetaToolChoiceApplyPatch object { type }` - - `"detailed"` + Forces the model to call the apply_patch tool when executing a tool call. - - `safety_identifier: optional string` + - `type: "apply_patch"` - 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](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + The tool to call. Always `apply_patch`. - - `service_tier: optional "auto" or "default" or "flex" or 2 more` + - `"apply_patch"` - Specifies the processing type used for serving the request. + - `BetaToolChoiceShell object { type }` - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](https://platform.openai.com/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'. + Forces the model to call the shell tool when a tool call is required. - 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: "shell"` - - `"auto"` + The tool to call. Always `shell`. - - `"default"` + - `"shell"` - - `"flex"` + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - - `"scale"` + 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. - - `"priority"` + We support the following categories of tools: - - `status: optional BetaResponseStatus` + - **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 status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + - `Function object { name, parameters, strict, 5 more }` - - `"completed"` + 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). - - `"failed"` + - `name: string` - - `"in_progress"` + The name of the function to call. - - `"cancelled"` + - `parameters: map[unknown]` - - `"queued"` + A JSON schema object describing the parameters of the function. - - `"incomplete"` + - `strict: boolean` - - `text: optional BetaResponseTextConfig` + Whether strict parameter validation is enforced for this function tool. - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + - `type: "function"` - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + The type of the function tool. Always `function`. - - `format: optional BetaResponseFormatTextConfig` + - `"function"` - An object specifying the format that the model must output. + - `allowed_callers: optional array of "direct" or "programmatic"` - Configuring `{ "type": "json_schema" }` enables Structured Outputs, - which ensures the model will match your supplied JSON schema. Learn more in the - [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + The tool invocation context(s). - The default format is `{ "type": "text" }` with no additional options. + - `"direct"` - **Not recommended for gpt-4o and newer models:** + - `"programmatic"` - 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 function is deferred and loaded via tool search. - Default response format. Used to generate text responses. + - `description: optional string` - - `type: "text"` + A description of the function. Used by the model to determine whether or not to call the function. - The type of response format being defined. Always `text`. + - `output_schema: optional map[unknown]` - - `"text"` + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + 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). - - `name: string` + - `type: "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. + The type of the file search tool. Always `file_search`. - - `schema: 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/). + - `vector_store_ids: array of string` - - `type: "json_schema"` + The IDs of the vector stores to search. - The type of response format being defined. Always `json_schema`. + - `filters: optional object { key, type, value } or object { filters, type }` - - `"json_schema"` + A filter to apply. - - `description: optional string` + - `ComparisonFilter object { key, type, value }` - A description of what the response format is for, used by the model to - determine how to respond in the format. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `strict: optional boolean` + - `key: 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](https://platform.openai.com/docs/guides/structured-outputs). + The key to compare against the value. - - `JSONObject object { type }` + - `type: "eq" or "ne" or "gt" or 5 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. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `type: "json_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 - The type of response format being defined. Always `json_object`. + - `"eq"` - - `"json_object"` + - `"ne"` - - `verbosity: optional "low" or "medium" or "high"` + - `"gt"` - 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`. + - `"gte"` - - `"low"` + - `"lt"` - - `"medium"` + - `"lte"` - - `"high"` + - `"in"` - - `top_logprobs: optional number` + - `"nin"` - 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. + - `value: string or number or boolean or array of string or number` - - `truncation: optional "auto" or "disabled"` + The value to compare against the attribute key; supports string, number, or boolean types. - The truncation strategy to use for the model response. + - `string` - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + - `number` - - `"auto"` + - `boolean` - - `"disabled"` + - `array of string or number` - - `usage: optional BetaResponseUsage` + - `string` - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + - `number` - - `input_tokens: number` + - `CompoundFilter object { filters, type }` - The number of input tokens. + Combine multiple filters using `and` or `or`. - - `input_tokens_details: object { cache_write_tokens, cached_tokens }` + - `filters: array of object { key, type, value } or unknown` - A detailed breakdown of the input tokens. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `cache_write_tokens: number` + - `ComparisonFilter object { key, type, value }` - The number of input tokens that were written to the cache. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `cached_tokens: number` + - `key: string` - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + The key to compare against the value. - - `output_tokens: number` + - `type: "eq" or "ne" or "gt" or 5 more` - The number of output tokens. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `output_tokens_details: object { reasoning_tokens }` + - `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 detailed breakdown of the output tokens. + - `"eq"` - - `reasoning_tokens: number` + - `"ne"` - The number of reasoning tokens. + - `"gt"` - - `total_tokens: number` + - `"gte"` - The total number of tokens used. + - `"lt"` - - `user: optional string` + - `"lte"` - 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](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `"in"` - - `sequence_number: number` + - `"nin"` - The sequence number for this event. + - `value: string or number or boolean or array of string or number` - - `type: "response.completed"` + The value to compare against the attribute key; supports string, number, or boolean types. - The type of the event. Always `response.completed`. + - `string` - - `"response.completed"` + - `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` -### Beta Response Computer Tool Call Output Screenshot + - `unknown` -- `BetaResponseComputerToolCallOutputScreenshot object { type, file_id, image_url }` + - `type: "and" or "or"` - A computer screenshot image used with the computer use tool. + Type of operation: `and` or `or`. - - `type: "computer_screenshot"` + - `"and"` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `"or"` - - `"computer_screenshot"` + - `max_num_results: optional number` - - `file_id: optional string` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - The identifier of an uploaded file that contains the screenshot. + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `image_url: optional string` + Ranking options for search. - The URL of the screenshot image. + - `hybrid_search: optional object { embedding_weight, text_weight }` -### Beta Response Container Reference + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. -- `BetaResponseContainerReference object { container_id, type }` + - `embedding_weight: number` - Represents a container created with /v1/containers. + The weight of the embedding in the reciprocal ranking fusion. - - `container_id: string` + - `text_weight: number` - - `type: "container_reference"` + The weight of the text in the reciprocal ranking fusion. - The environment type. Always `container_reference`. + - `ranker: optional "auto" or "default-2024-11-15"` - - `"container_reference"` + The ranker to use for the file search. -### Beta Response Content + - `"auto"` -- `BetaResponseContent = BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile or 3 more` + - `"default-2024-11-15"` - Multi-modal input and output contents. + - `score_threshold: optional number` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + 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 text input to the model. + - `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 input to the model. + - `type: "computer"` - - `type: "input_text"` + The type of the computer tool. Always `computer`. - The type of the input item. Always `input_text`. + - `"computer"` - - `"input_text"` + - `ComputerUsePreview object { display_height, display_width, environment, 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. + - `display_height: number` - - `mode: "explicit"` + The height of the computer display. - The breakpoint mode. Always `explicit`. + - `display_width: number` - - `"explicit"` + The width of the computer display. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `environment: "windows" or "mac" or "linux" or 2 more` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The type of computer environment to control. - - `detail: "low" or "high" or "auto" or "original"` + - `"windows"` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `"mac"` - - `"low"` + - `"linux"` - - `"high"` + - `"ubuntu"` - - `"auto"` + - `"browser"` - - `"original"` + - `type: "computer_use_preview"` - - `type: "input_image"` + The type of the computer use tool. Always `computer_use_preview`. - The type of the input item. Always `input_image`. + - `"computer_use_preview"` - - `"input_image"` + - `WebSearch object { type, filters, search_context_size, user_location }` - - `file_id: optional string` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - The ID of the file to be sent to the model. + - `type: "web_search" or "web_search_2025_08_26"` - - `image_url: optional string` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `"web_search"` - - `prompt_cache_breakpoint: optional object { mode }` + - `"web_search_2025_08_26"` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `filters: optional object { allowed_domains }` - - `mode: "explicit"` + Filters for the search. - The breakpoint mode. Always `explicit`. + - `allowed_domains: optional array of string` - - `"explicit"` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - A file input to the model. + - `search_context_size: optional "low" or "medium" or "high"` - - `type: "input_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. - The type of the input item. Always `input_file`. + - `"low"` - - `"input_file"` + - `"medium"` - - `detail: optional "auto" or "low" or "high"` + - `"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`. + - `user_location: optional object { city, country, region, 2 more }` - - `"auto"` + The approximate location of the user. - - `"low"` + - `city: optional string` - - `"high"` + Free text input for the city of the user, e.g. `San Francisco`. - - `file_data: optional string` + - `country: optional string` - The content 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`. - - `file_id: optional string` + - `region: optional string` - The ID of the file to be sent to the model. + Free text input for the region of the user, e.g. `California`. - - `file_url: optional string` + - `timezone: optional string` - The URL of the file to be sent to the model. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `filename: optional string` + - `type: optional "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. + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `mode: "explicit"` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - The breakpoint mode. Always `explicit`. + - `server_label: string` - - `"explicit"` + A label for this MCP server, used to identify it in tool calls. - - `BetaResponseOutputText object { annotations, text, type, logprobs }` + - `type: "mcp"` - A text output from the model. + The type of the MCP tool. Always `mcp`. - - `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 }` + - `"mcp"` - The annotations of the text output. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `FileCitation object { file_id, filename, index, type }` + The tool invocation context(s). - A citation to a file. + - `"direct"` - - `file_id: string` + - `"programmatic"` - The ID of the file. + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `filename: string` + List of allowed tool names or a filter object. - The filename of the file cited. + - `McpAllowedTools = array of string` - - `index: number` + A string array of allowed tool names - The index of the file in the list of files. + - `McpToolFilter object { read_only, tool_names }` - - `type: "file_citation"` + A filter object to specify which tools are allowed. - The type of the file citation. Always `file_citation`. + - `read_only: optional boolean` - - `"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. - - `URLCitation object { end_index, start_index, title, 2 more }` + - `tool_names: optional array of string` - A citation for a web resource used to generate a model response. + List of allowed tool names. - - `end_index: number` + - `authorization: optional string` - The index of the last character of the URL citation in the message. + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - - `start_index: number` + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - The index of the first character of the URL citation in the message. + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). - - `title: string` + Currently supported `connector_id` values are: - The title of the web resource. + - 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: "url_citation"` + - `"connector_dropbox"` - The type of the URL citation. Always `url_citation`. + - `"connector_gmail"` - - `"url_citation"` + - `"connector_googlecalendar"` - - `url: string` + - `"connector_googledrive"` - The URL of the web resource. + - `"connector_microsoftteams"` - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + - `"connector_outlookcalendar"` - A citation for a container file used to generate a model response. + - `"connector_outlookemail"` - - `container_id: string` + - `"connector_sharepoint"` - The ID of the container file. + - `defer_loading: optional boolean` - - `end_index: number` + Whether this MCP tool is deferred and discovered via tool search. - The index of the last character of the container file citation in the message. + - `headers: optional map[string]` - - `file_id: string` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - The ID of the file. + - `require_approval: optional object { always, never } or "always" or "never"` - - `filename: string` + Specify which of the MCP server's tools require approval. - The filename of the container file cited. + - `McpToolApprovalFilter object { always, never }` - - `start_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 first character of the container file citation in the message. + - `always: optional object { read_only, tool_names }` - - `type: "container_file_citation"` + A filter object to specify which tools are allowed. - The type of the container file citation. Always `container_file_citation`. + - `read_only: optional boolean` - - `"container_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. - - `FilePath object { file_id, index, type }` + - `tool_names: optional array of string` - A path to a file. + List of allowed tool names. - - `file_id: string` + - `never: optional object { read_only, tool_names }` - The ID of the file. + 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_path"` + - `tool_names: optional array of string` - The type of the file path. Always `file_path`. + List of allowed tool names. - - `"file_path"` + - `McpToolApprovalSetting = "always" or "never"` - - `text: 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 text output from the model. + - `"always"` - - `type: "output_text"` + - `"never"` - The type of the output text. Always `output_text`. + - `server_description: optional string` - - `"output_text"` + Optional description of the MCP server, used to provide more context. - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + - `server_url: optional string` - - `token: string` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `bytes: array of number` + - `tunnel_id: optional string` - - `logprob: 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. - - `top_logprobs: array of object { token, bytes, logprob }` + - `CodeInterpreter object { container, type, allowed_callers }` - - `token: string` + A tool that runs Python code to help generate a response to a prompt. - - `bytes: array of number` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `logprob: 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. - - `BetaResponseOutputRefusal object { refusal, type }` + - `string` - A refusal from the model. + The container ID. - - `refusal: string` + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - The refusal explanation from the model. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `type: "refusal"` + - `type: "auto"` - The type of the refusal. Always `refusal`. + Always `auto`. - - `"refusal"` + - `"auto"` - - `ReasoningText object { text, type }` + - `file_ids: optional array of string` - Reasoning text from the model. + An optional list of uploaded files to make available to your code. - - `text: string` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - The reasoning text from the model. + The memory limit for the code interpreter container. - - `type: "reasoning_text"` + - `"1g"` - The type of the reasoning text. Always `reasoning_text`. + - `"4g"` - - `"reasoning_text"` + - `"16g"` -### Beta Response Content Part Added Event + - `"64g"` -- `BetaResponseContentPartAddedEvent object { content_index, item_id, output_index, 4 more }` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - Emitted when a new content part is added. + Network access policy for the container. - - `content_index: number` + - `BetaContainerNetworkPolicyDisabled object { type }` - The index of the content part that was added. + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `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, text, type, logprobs }` + - `"programmatic"` - A text output from the model. + - `ProgrammaticToolCalling object { type }` - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + - `type: "programmatic_tool_calling"` - The annotations of the text output. + The type of the tool. Always `programmatic_tool_calling`. - - `FileCitation object { file_id, filename, index, type }` + - `"programmatic_tool_calling"` - A citation to a file. + - `ImageGeneration object { type, action, background, 9 more }` - - `file_id: string` + A tool that generates images using the GPT image models. - The ID of the file. + - `type: "image_generation"` - - `filename: string` + The type of the image generation tool. Always `image_generation`. - The filename of the file cited. + - `"image_generation"` - - `index: number` + - `action: optional "generate" or "edit" or "auto"` - The index of the file in the list of files. + Whether to generate a new image or edit an existing image. Default: `auto`. - - `type: "file_citation"` + - `"generate"` - The type of the file citation. Always `file_citation`. + - `"edit"` - - `"file_citation"` + - `"auto"` - - `URLCitation object { end_index, start_index, title, 2 more }` + - `background: optional "transparent" or "opaque" or "auto"` - A citation for a web resource used to generate a model response. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - - `end_index: number` + - `"transparent"` - The index of the last character of the URL citation in the message. + - `"opaque"` - - `start_index: number` + - `"auto"` - The index of the first character of the URL citation in the message. + - `input_fidelity: optional "high" or "low"` - - `title: 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 title of the web resource. + - `"high"` - - `type: "url_citation"` + - `"low"` - The type of the URL citation. Always `url_citation`. + - `input_image_mask: optional object { file_id, image_url }` - - `"url_citation"` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `url: string` + - `file_id: optional string` - The URL of the web resource. + File ID for the mask image. - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + - `image_url: optional string` - A citation for a container file used to generate a model response. + Base64-encoded mask image. - - `container_id: string` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - The ID of the container file. + The image generation model to use. Default: `gpt-image-1`. - - `end_index: number` + - `string` - The index of the last character of the container file citation in the message. + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `file_id: string` + The image generation model to use. Default: `gpt-image-1`. - The ID of the file. + - `"gpt-image-1"` - - `filename: string` + - `"gpt-image-1-mini"` - The filename of the container file cited. + - `"gpt-image-1.5"` - - `start_index: number` + - `moderation: optional "auto" or "low"` - The index of the first character of the container file citation in the message. + Moderation level for the generated image. Default: `auto`. - - `type: "container_file_citation"` + - `"auto"` - The type of the container file citation. Always `container_file_citation`. + - `"low"` - - `"container_file_citation"` + - `output_compression: optional number` - - `FilePath object { file_id, index, type }` + Compression level for the output image. Default: 100. - A path to a file. + - `output_format: optional "png" or "webp" or "jpeg"` - - `file_id: string` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - The ID of the file. + - `"png"` - - `index: number` + - `"webp"` - The index of the file in the list of files. + - `"jpeg"` - - `type: "file_path"` + - `partial_images: optional number` - The type of the file path. Always `file_path`. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `"file_path"` + - `quality: optional "low" or "medium" or "high" or "auto"` - - `text: string` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - The text output from the model. + - `"low"` - - `type: "output_text"` + - `"medium"` - The type of the output text. Always `output_text`. + - `"high"` - - `"output_text"` + - `"auto"` - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `token: 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`. - - `bytes: array of number` + - `string` - - `logprob: number` + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `top_logprobs: array of object { token, bytes, logprob }` + 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`. - - `token: string` + - `"1024x1024"` - - `bytes: array of number` + - `"1024x1536"` - - `logprob: number` + - `"1536x1024"` - - `BetaResponseOutputRefusal object { refusal, type }` + - `"auto"` - A refusal from the model. + - `LocalShell object { type }` - - `refusal: string` + A tool that allows the model to execute shell commands in a local environment. - The refusal explanation from the model. + - `type: "local_shell"` - - `type: "refusal"` + The type of the local shell tool. Always `local_shell`. - The type of the refusal. Always `refusal`. + - `"local_shell"` - - `"refusal"` + - `Shell object { type, allowed_callers, environment }` - - `ReasoningText object { text, type }` + A tool that allows the model to execute shell commands. - Reasoning text from the model. + - `type: "shell"` - - `text: string` + The type of the shell tool. Always `shell`. - The reasoning text from the model. + - `"shell"` - - `type: "reasoning_text"` + - `allowed_callers: optional array of "direct" or "programmatic"` - The type of the reasoning text. Always `reasoning_text`. + The tool invocation context(s). - - `"reasoning_text"` + - `"direct"` - - `sequence_number: number` + - `"programmatic"` - The sequence number of this event. + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - `type: "response.content_part.added"` + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - The type of the event. Always `response.content_part.added`. + - `BetaLocalEnvironment object { type, skills }` - - `"response.content_part.added"` + - `BetaContainerReference object { container_id, type }` - - `agent: optional object { agent_name }` + - `Custom object { name, type, allowed_callers, 3 more }` - The agent that owns this multi-agent streaming event. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `agent_name: string` + - `name: string` - The canonical name of the agent that produced this item. + The name of the custom tool, used to identify it in tool calls. -### Beta Response Content Part Done Event + - `type: "custom"` -- `BetaResponseContentPartDoneEvent object { content_index, item_id, output_index, 4 more }` + The type of the custom tool. Always `custom`. - Emitted when a content part is done. + - `"custom"` - - `content_index: number` + - `allowed_callers: optional array of "direct" or "programmatic"` - The index of the content part that is done. + The tool invocation context(s). - - `item_id: string` + - `"direct"` - The ID of the output item that the content part was added to. + - `"programmatic"` - - `output_index: number` + - `defer_loading: optional boolean` - The index of the output item that the content part was added to. + Whether this tool should be deferred and discovered via tool search. - - `part: BetaResponseOutputText or BetaResponseOutputRefusal or object { text, type }` + - `description: optional string` - The content part that is done. + Optional description of the custom tool, used to provide more context. - - `BetaResponseOutputText object { annotations, text, type, logprobs }` + - `format: optional object { type } or object { definition, syntax, type }` - A text output from the model. + The input format for the custom tool. Default is unconstrained 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 object { type }` - The annotations of the text output. + Unconstrained free-form text. - - `FileCitation object { file_id, filename, index, type }` + - `type: "text"` - A citation to a file. + Unconstrained text format. Always `text`. - - `file_id: string` + - `"text"` - The ID of the file. + - `Grammar object { definition, syntax, type }` - - `filename: string` + A grammar defined by the user. - The filename of the file cited. + - `definition: string` - - `index: number` + The grammar definition. - The index of the file in the list of files. + - `syntax: "lark" or "regex"` - - `type: "file_citation"` + The syntax of the grammar definition. One of `lark` or `regex`. - The type of the file citation. Always `file_citation`. + - `"lark"` - - `"file_citation"` + - `"regex"` - - `URLCitation object { end_index, start_index, title, 2 more }` + - `type: "grammar"` - A citation for a web resource used to generate a model response. + Grammar format. Always `grammar`. - - `end_index: number` + - `"grammar"` - The index of the last character of the URL citation in the message. + - `Namespace object { description, name, tools, type }` - - `start_index: number` + Groups function/custom tools under a shared namespace. - The index of the first character of the URL citation in the message. + - `description: string` - - `title: string` + A description of the namespace shown to the model. - The title of the web resource. + - `name: string` - - `type: "url_citation"` + The namespace name used in tool calls (for example, `crm`). - The type of the URL citation. Always `url_citation`. + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - - `"url_citation"` + The function/custom tools available inside this namespace. - - `url: string` + - `Function object { name, type, allowed_callers, 5 more }` - The URL of the web resource. + - `name: string` - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + - `type: "function"` - A citation for a container file used to generate a model response. + - `"function"` - - `container_id: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The ID of the container file. + The tool invocation context(s). - - `end_index: number` + - `"direct"` - The index of the last character of the container file citation in the message. + - `"programmatic"` - - `file_id: string` + - `defer_loading: optional boolean` - The ID of the file. + Whether this function should be deferred and discovered via tool search. - - `filename: string` + - `description: optional string` - The filename of the container file cited. + - `output_schema: optional map[unknown]` - - `start_index: number` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - The index of the first character of the container file citation in the message. + - `parameters: optional unknown` - - `type: "container_file_citation"` + - `strict: optional boolean` - The type of the container file citation. Always `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. - - `"container_file_citation"` + - `Custom object { name, type, allowed_callers, 3 more }` - - `FilePath object { file_id, index, type }` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - A path to a file. + - `name: string` - - `file_id: string` + The name of the custom tool, used to identify it in tool calls. - The ID of the file. + - `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_path"` + - `allowed_callers: optional array of "direct" or "programmatic"` - The type of the file path. Always `file_path`. + The tool invocation context(s). - - `"file_path"` + - `"direct"` - - `text: string` + - `"programmatic"` - The text output from the model. + - `defer_loading: optional boolean` - - `type: "output_text"` + Whether this tool should be deferred and discovered via tool search. - The type of the output text. Always `output_text`. + - `description: optional string` - - `"output_text"` + Optional description of the custom tool, used to provide more context. - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + - `format: optional object { type } or object { definition, syntax, type }` - - `token: string` + The input format for the custom tool. Default is unconstrained text. - - `bytes: array of number` + - `Text object { type }` - - `logprob: number` + Unconstrained free-form text. - - `top_logprobs: array of object { token, bytes, logprob }` + - `type: "text"` - - `token: string` + Unconstrained text format. Always `text`. - - `bytes: array of number` + - `"text"` - - `logprob: number` + - `Grammar object { definition, syntax, type }` - - `BetaResponseOutputRefusal object { refusal, type }` + A grammar defined by the user. - A refusal from the model. + - `definition: string` - - `refusal: string` + The grammar definition. - The refusal explanation from the model. + - `syntax: "lark" or "regex"` - - `type: "refusal"` + The syntax of the grammar definition. One of `lark` or `regex`. - The type of the refusal. Always `refusal`. + - `"lark"` - - `"refusal"` + - `"regex"` - - `ReasoningText object { text, type }` + - `type: "grammar"` - Reasoning text from the model. + Grammar format. Always `grammar`. - - `text: string` + - `"grammar"` - The reasoning text from the model. + - `type: "namespace"` - - `type: "reasoning_text"` + The type of the tool. Always `namespace`. - The type of the reasoning text. Always `reasoning_text`. + - `"namespace"` - - `"reasoning_text"` + - `ToolSearch object { type, description, execution, parameters }` - - `sequence_number: number` + Hosted or BYOT tool search configuration for deferred tools. - The sequence number of this event. + - `type: "tool_search"` - - `type: "response.content_part.done"` + The type of the tool. Always `tool_search`. - The type of the event. Always `response.content_part.done`. + - `"tool_search"` - - `"response.content_part.done"` + - `description: optional string` - - `agent: optional object { agent_name }` + Description shown to the model for a client-executed tool search tool. - The agent that owns this multi-agent streaming event. + - `execution: optional "server" or "client"` - - `agent_name: string` + Whether tool search is executed by the server or by the client. - The canonical name of the agent that produced this item. + - `"server"` -### Beta Response Conversation Param + - `"client"` -- `BetaResponseConversationParam object { id }` + - `parameters: optional unknown` - The conversation that this response belongs to. + 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 conversation. + 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). -### Beta Response Created Event + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` -- `BetaResponseCreatedEvent object { response, sequence_number, type, agent }` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - An event that is emitted when a response is created. + - `"web_search_preview"` - - `response: BetaResponse` + - `"web_search_preview_2025_03_11"` - The response that was created. + - `search_content_types: optional array of "text" or "image"` - - `id: string` + - `"text"` - Unique identifier for this Response. + - `"image"` - - `created_at: number` + - `search_context_size: optional "low" or "medium" or "high"` - Unix timestamp (in seconds) of when this Response was 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. - - `error: BetaResponseError` + - `"low"` - An error object returned when the model fails to generate a Response. + - `"medium"` - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 16 more` + - `"high"` - The error code for the response. + - `user_location: optional object { type, city, country, 2 more }` - - `"server_error"` + The user's location. - - `"rate_limit_exceeded"` + - `type: "approximate"` - - `"invalid_prompt"` + The type of location approximation. Always `approximate`. - - `"bio_policy"` + - `"approximate"` - - `"vector_store_timeout"` + - `city: optional string` - - `"invalid_image"` + Free text input for the city of the user, e.g. `San Francisco`. - - `"invalid_image_format"` + - `country: optional string` - - `"invalid_base64_image"` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `"invalid_image_url"` + - `region: optional string` - - `"image_too_large"` + Free text input for the region of the user, e.g. `California`. - - `"image_too_small"` + - `timezone: optional string` - - `"image_parse_error"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `"image_content_policy_violation"` + - `ApplyPatch object { type, allowed_callers }` - - `"invalid_image_mode"` + Allows the assistant to create, delete, or update files using unified diffs. - - `"image_file_too_large"` + - `type: "apply_patch"` - - `"unsupported_image_media_type"` + The type of the tool. Always `apply_patch`. - - `"empty_image_file"` + - `"apply_patch"` - - `"failed_to_download_image"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"image_file_not_found"` + The tool invocation context(s). - - `message: string` + - `"direct"` - A human-readable description of the error. + - `"programmatic"` - - `incomplete_details: object { reason }` + - `top_p: number` - Details about why the response is 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. - - `reason: optional "max_output_tokens" or "content_filter"` + We generally recommend altering this or `temperature` but not both. - The reason why the response is incomplete. + - `background: optional boolean` - - `"max_output_tokens"` + Whether to run the model response in the background. + [Learn more](/docs/guides/background). - - `"content_filter"` + - `completed_at: optional number` - - `instructions: string or array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - A system (or developer) message inserted into the model's context. + - `conversation: optional object { id }` - 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 conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - - `string` + - `id: string` - A text input to the model, equivalent to a text input with the - `developer` role. + The unique ID of the conversation that this response was associated with. - - `InputItemList = array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + - `max_output_tokens: optional number` - A list of one or many input items to the model, containing - different content types. + 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). - - `BetaEasyInputMessage object { content, role, phase, type }` + - `max_tool_calls: optional 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 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. - - `content: string or BetaResponseInputMessageContentList` + - `moderation: optional object { input, output }` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + Moderation results for the response input and output, if moderated completions were requested. - - `TextInput = string` + - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` - A text input to the model. + Moderation for the response input. - - `BetaResponseInputMessageContentList = array of BetaResponseInputContent` + - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` - A list of one or many input items to the model, containing different content - types. + A moderation result produced for the response input or output. - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `categories: map[boolean]` - A text input to the model. + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `text: string` + - `category_applied_input_types: map[array of "text" or "image"]` - The text input to the model. + Which modalities of input are reflected by the score for each category. - - `type: "input_text"` + - `"text"` - The type of the input item. Always `input_text`. + - `"image"` - - `"input_text"` + - `category_scores: map[number]` - - `prompt_cache_breakpoint: optional object { mode }` + A dictionary of moderation categories to scores. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `flagged: boolean` - - `mode: "explicit"` + A boolean indicating whether the content was flagged by any category. - The breakpoint mode. Always `explicit`. + - `model: string` - - `"explicit"` + The moderation model that produced this result. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `type: "moderation_result"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The object type, which was always `moderation_result` for successful moderation results. - - `detail: "low" or "high" or "auto" or "original"` + - `"moderation_result"` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `Error object { code, message, type }` - - `"low"` + An error produced while attempting moderation for the response input or output. - - `"high"` + - `code: string` - - `"auto"` + The error code. - - `"original"` + - `message: string` - - `type: "input_image"` + The error message. - The type of the input item. Always `input_image`. + - `type: "error"` - - `"input_image"` + 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. - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `"text"` - A file input to the model. + - `"image"` - - `type: "input_file"` + - `category_scores: map[number]` - The type of the input item. Always `input_file`. + A dictionary of moderation categories to scores. - - `"input_file"` + - `flagged: boolean` - - `detail: optional "auto" or "low" or "high"` + A boolean indicating whether the content was flagged by any category. - 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`. + - `model: string` - - `"auto"` + The moderation model that produced this result. - - `"low"` + - `type: "moderation_result"` - - `"high"` + The object type, which was always `moderation_result` for successful moderation results. - - `file_data: optional string` + - `"moderation_result"` - The content of the file to be sent to the model. + - `Error object { code, message, type }` - - `file_id: optional string` + An error produced while attempting moderation for the response input or output. - The ID of the file to be sent to the model. + - `code: string` - - `file_url: optional string` + The error code. - The URL of the file to be sent to the model. + - `message: string` - - `filename: optional string` + The error message. - The name of the file to be sent to the model. + - `type: "error"` - - `prompt_cache_breakpoint: optional object { mode }` + The object type, which was always `error` for moderation failures. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `"error"` - - `mode: "explicit"` + - `output_text: optional string` - The breakpoint mode. Always `explicit`. + SDK-only convenience property that contains the aggregated text output + from all `output_text` items in the `output` array, if any are present. + Supported in the Python and JavaScript SDKs. - - `"explicit"` + - `previous_response_id: optional string` - - `role: "user" or "assistant" or "system" or "developer"` + 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 role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + - `prompt: optional BetaResponsePrompt` - - `"user"` + Reference to a prompt template and its variables. + [Learn more](/docs/guides/text?api-mode=responses#reusable-prompts). - - `"assistant"` + - `id: string` - - `"system"` + The unique identifier of the prompt template to use. - - `"developer"` + - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` - - `phase: optional "commentary" or "final_answer"` + 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. - 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"` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `"final_answer"` + A text input to the model. - - `type: optional "message"` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - The type of the message input. Always `message`. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `"message"` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `Message object { content, role, agent, 2 more }` + A file input to the model. - 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. + - `version: optional string` - - `content: BetaResponseInputMessageContentList` + Optional version of the prompt template. - A list of one or many input items to the model, containing different content - types. + - `prompt_cache_key: optional string` - - `role: "user" or "system" or "developer"` + 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 role of the message input. One of `user`, `system`, or `developer`. + - `prompt_cache_options: optional object { mode, ttl }` - - `"user"` + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - - `"system"` + - `mode: "implicit" or "explicit"` - - `"developer"` + Whether implicit prompt-cache breakpoints were enabled. - - `agent: optional object { agent_name }` + - `"implicit"` - The agent that produced this item. + - `"explicit"` - - `agent_name: string` + - `ttl: "30m"` - The canonical name of the agent that produced this item. + The minimum lifetime applied to each cache breakpoint. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"30m"` - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `prompt_cache_retention: optional "in_memory" or "24h"` - - `"in_progress"` + Deprecated. Use `prompt_cache_options.ttl` instead. - - `"completed"` + 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. - - `"incomplete"` + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - - `type: optional "message"` + - 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 message input. Always set to `message`. + - `"in_memory"` - - `"message"` + - `"24h"` - - `BetaResponseOutputMessage object { id, content, role, 4 more }` + - `reasoning: optional object { context, effort, generate_summary, 2 more }` - An output message from the model. + **gpt-5 and o-series models only** - - `id: string` + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - The unique ID of the output message. + - `context: optional "auto" or "current_turn" or "all_turns"` - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + Controls which reasoning items are rendered back to the model on later turns. + When returned on a response, this is the effective reasoning context mode + used for the response. - The content of the output message. + - `"auto"` - - `BetaResponseOutputText object { annotations, text, type, logprobs }` + - `"current_turn"` - A text output from the model. + - `"all_turns"` - - `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 }` + - `effort: optional "none" or "minimal" or "low" or 4 more` - The annotations of the text 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. - - `FileCitation object { file_id, filename, index, type }` + - `"none"` - A citation to a file. + - `"minimal"` - - `file_id: string` + - `"low"` - The ID of the file. + - `"medium"` - - `filename: string` + - `"high"` - The filename of the file cited. + - `"xhigh"` - - `index: number` + - `"max"` - The index of the file in the list of files. + - `generate_summary: optional "auto" or "concise" or "detailed"` - - `type: "file_citation"` + **Deprecated:** use `summary` instead. - The type of the file citation. Always `file_citation`. + 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`. - - `"file_citation"` + - `"auto"` - - `URLCitation object { end_index, start_index, title, 2 more }` + - `"concise"` - A citation for a web resource used to generate a model response. + - `"detailed"` - - `end_index: number` + - `mode: optional string or "standard" or "pro"` - The index of the last character of the URL citation in the message. + Controls the reasoning execution mode for the request. - - `start_index: number` + When returned on a response, this is the effective execution mode. - The index of the first character of the URL citation in the message. + - `string` - - `title: string` + - `"standard" or "pro"` - The title of the web resource. + Controls the reasoning execution mode for the request. - - `type: "url_citation"` + When returned on a response, this is the effective execution mode. - The type of the URL citation. Always `url_citation`. + - `"standard"` - - `"url_citation"` + - `"pro"` - - `url: string` + - `summary: optional "auto" or "concise" or "detailed"` - The URL of the web resource. + 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`. - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - A citation for a container file used to generate a model response. + - `"auto"` - - `container_id: string` + - `"concise"` - The ID of the container file. + - `"detailed"` - - `end_index: number` + - `safety_identifier: optional string` - The index of the last character of the container file citation in the message. + 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). - - `file_id: string` + - `service_tier: optional "auto" or "default" or "flex" or 2 more` - The ID of the file. + Specifies the processing type used for serving the request. - - `filename: 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 filename of the container file cited. + 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. - - `start_index: number` + - `"auto"` - The index of the first character of the container file citation in the message. + - `"default"` - - `type: "container_file_citation"` + - `"flex"` - The type of the container file citation. Always `container_file_citation`. + - `"scale"` - - `"container_file_citation"` + - `"priority"` - - `FilePath object { file_id, index, type }` + - `status: optional BetaResponseStatus` - A path to a file. + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - - `file_id: string` + - `"completed"` - The ID of the file. + - `"failed"` - - `index: number` + - `"in_progress"` - The index of the file in the list of files. + - `"cancelled"` - - `type: "file_path"` + - `"queued"` - The type of the file path. Always `file_path`. + - `"incomplete"` - - `"file_path"` + - `text: optional BetaResponseTextConfig` - - `text: string` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - The text output from the model. + - [Text inputs and outputs](/docs/guides/text) + - [Structured Outputs](/docs/guides/structured-outputs) - - `type: "output_text"` + - `format: optional BetaResponseFormatTextConfig` - The type of the output text. Always `output_text`. + An object specifying the format that the model must output. - - `"output_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). - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + The default format is `{ "type": "text" }` with no additional options. - - `token: string` + **Not recommended for gpt-4o and newer models:** - - `bytes: array of 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. - - `logprob: number` + - `Text object { type }` - - `top_logprobs: array of object { token, bytes, logprob }` + Default response format. Used to generate text responses. - - `token: string` + - `type: "text"` - - `bytes: array of number` + The type of response format being defined. Always `text`. - - `logprob: number` + - `"text"` - - `BetaResponseOutputRefusal object { refusal, type }` + - `BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` - A refusal from the model. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - - `refusal: string` + - `name: string` - The refusal explanation from 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. - - `type: "refusal"` + - `schema: map[unknown]` - The type of the refusal. Always `refusal`. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `"refusal"` + - `type: "json_schema"` - - `role: "assistant"` + The type of response format being defined. Always `json_schema`. - The role of the output message. Always `assistant`. + - `"json_schema"` - - `"assistant"` + - `description: optional string` - - `status: "in_progress" or "completed" or "incomplete"` + 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 input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `strict: optional boolean` - - `"in_progress"` + 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"` + - `JSONObject object { type }` - - `"incomplete"` + 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: "message"` + - `type: "json_object"` - The type of the output message. Always `message`. + The type of response format being defined. Always `json_object`. - - `"message"` + - `"json_object"` - - `agent: optional object { agent_name }` + - `verbosity: optional "low" or "medium" or "high"` - The agent that produced this item. + 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`. - - `agent_name: string` + - `"low"` - The canonical name of the agent that produced this item. + - `"medium"` - - `phase: optional "commentary" or "final_answer"` + - `"high"` - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + - `top_logprobs: optional number` - - `"commentary"` + 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. - - `"final_answer"` + - `truncation: optional "auto" or "disabled"` - - `FileSearchCall object { id, queries, status, 3 more }` + The truncation strategy to use for the model response. - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. - - `id: string` + - `"auto"` - The unique ID of the file search tool call. + - `"disabled"` - - `queries: array of string` + - `usage: optional BetaResponseUsage` - The queries used to search for files. + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - - `status: "in_progress" or "searching" or "completed" or 2 more` + - `input_tokens: number` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + The number of input tokens. - - `"in_progress"` + - `input_tokens_details: object { cache_write_tokens, cached_tokens }` - - `"searching"` + A detailed breakdown of the input tokens. - - `"completed"` + - `cache_write_tokens: number` - - `"incomplete"` + The number of input tokens that were written to the cache. - - `"failed"` + - `cached_tokens: number` - - `type: "file_search_call"` + The number of tokens that were retrieved from the cache. + [More on prompt caching](/docs/guides/prompt-caching). - The type of the file search tool call. Always `file_search_call`. + - `output_tokens: number` - - `"file_search_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. - - `results: optional array of object { attributes, file_id, filename, 2 more }` + - `total_tokens: number` - The results of the file search tool call. + The total number of tokens used. - - `attributes: optional map[string or number or boolean]` + - `user: 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. + 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). - - `string` + - `sequence_number: number` - - `number` + The sequence number of this event. - - `boolean` + - `type: "response.failed"` - - `file_id: optional string` + The type of the event. Always `response.failed`. - The unique ID of the file. + - `"response.failed"` - - `filename: optional string` + - `agent: optional object { agent_name }` - The name of the file. + The agent that owns this multi-agent streaming event. - - `score: optional number` + - `agent_name: string` - The relevance score of the file - a value between 0 and 1. + The canonical name of the agent that produced this item. - - `text: optional string` +### Beta Response File Search Call Completed Event - The text that was retrieved from the file. +- `BetaResponseFileSearchCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` - - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` + Emitted when a file search call is completed (results found). - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + - `item_id: string` - - `id: string` + The ID of the output item that the file search call is initiated. - The unique ID of the computer call. + - `output_index: number` - - `call_id: string` + The index of the output item that the file search call is initiated. - An identifier used when responding to the tool call with output. + - `sequence_number: number` - - `pending_safety_checks: array of object { id, code, message }` + The sequence number of this event. - The pending safety checks for the computer call. + - `type: "response.file_search_call.completed"` - - `id: string` + The type of the event. Always `response.file_search_call.completed`. - The ID of the pending safety check. + - `"response.file_search_call.completed"` - - `code: optional string` + - `agent: optional object { agent_name }` - The type of the pending safety check. + The agent that owns this multi-agent streaming event. - - `message: optional string` + - `agent_name: string` - Details about the pending safety check. + The canonical name of the agent that produced this item. - - `status: "in_progress" or "completed" or "incomplete"` +### Beta Response File Search Call In Progress Event - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. +- `BetaResponseFileSearchCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` - - `"in_progress"` + Emitted when a file search call is initiated. - - `"completed"` + - `item_id: string` - - `"incomplete"` + The ID of the output item that the file search call is initiated. - - `type: "computer_call"` + - `output_index: number` - The type of the computer call. Always `computer_call`. + The index of the output item that the file search call is initiated. - - `"computer_call"` + - `sequence_number: number` - - `action: optional BetaComputerAction` + The sequence number of this event. - A click action. + - `type: "response.file_search_call.in_progress"` - - `Click object { button, type, x, 2 more }` + The type of the event. Always `response.file_search_call.in_progress`. - A click action. + - `"response.file_search_call.in_progress"` - - `button: "left" or "right" or "wheel" or 2 more` + - `agent: optional object { agent_name }` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + The agent that owns this multi-agent streaming event. - - `"left"` + - `agent_name: string` - - `"right"` + The canonical name of the agent that produced this item. - - `"wheel"` +### Beta Response File Search Call Searching Event - - `"back"` +- `BetaResponseFileSearchCallSearchingEvent object { item_id, output_index, sequence_number, 2 more }` - - `"forward"` + Emitted when a file search is currently searching. - - `type: "click"` + - `item_id: string` - Specifies the event type. For a click action, this property is always `click`. + The ID of the output item that the file search call is initiated. - - `"click"` + - `output_index: number` - - `x: number` + The index of the output item that the file search call is searching. - The x-coordinate where the click occurred. + - `sequence_number: number` - - `y: number` + The sequence number of this event. - The y-coordinate where the click occurred. + - `type: "response.file_search_call.searching"` - - `keys: optional array of string` + The type of the event. Always `response.file_search_call.searching`. - The keys being held while clicking. + - `"response.file_search_call.searching"` - - `DoubleClick object { keys, type, x, y }` + - `agent: optional object { agent_name }` - A double click action. + The agent that owns this multi-agent streaming event. - - `keys: array of string` + - `agent_name: string` - The keys being held while double-clicking. + The canonical name of the agent that produced this item. - - `type: "double_click"` +### Beta Response Format Text Config - Specifies the event type. For a double click action, this property is always set to `double_click`. +- `BetaResponseFormatTextConfig = object { type } or BetaResponseFormatTextJSONSchemaConfig or object { type }` - - `"double_click"` + An object specifying the format that the model must output. - - `x: 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). - The x-coordinate where the double click occurred. + The default format is `{ "type": "text" }` with no additional options. - - `y: number` + **Not recommended for gpt-4o and newer models:** - The y-coordinate where the double click occurred. + 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. - - `Drag object { path, type, keys }` + - `Text object { type }` - A drag action. + Default response format. Used to generate text responses. - - `path: array of object { x, y }` + - `type: "text"` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + The type of response format being defined. Always `text`. - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `"text"` - - `x: number` + - `BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` - The x-coordinate. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - - `y: number` + - `name: string` - The y-coordinate. + 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: "drag"` + - `schema: map[unknown]` - Specifies the event type. For a drag action, this property is always set to `drag`. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `"drag"` + - `type: "json_schema"` - - `keys: optional array of string` + The type of response format being defined. Always `json_schema`. - The keys being held while dragging the mouse. + - `"json_schema"` - - `Keypress object { keys, type }` + - `description: optional string` - A collection of keypresses the model would like to perform. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `keys: array of string` + - `strict: optional boolean` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + 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: "keypress"` + - `JSONObject object { type }` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + 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. - - `"keypress"` + - `type: "json_object"` - - `Move object { type, x, y, keys }` + The type of response format being defined. Always `json_object`. - A mouse move action. + - `"json_object"` - - `type: "move"` +### Beta Response Format Text JSON Schema Config - Specifies the event type. For a move action, this property is always set to `move`. +- `BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` - - `"move"` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - - `x: number` + - `name: string` - The x-coordinate to move to. + 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. - - `y: number` + - `schema: map[unknown]` - The y-coordinate to move to. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `keys: optional array of string` + - `type: "json_schema"` - The keys being held while moving the mouse. + The type of response format being defined. Always `json_schema`. - - `Screenshot object { type }` + - `"json_schema"` - A screenshot action. + - `description: optional string` - - `type: "screenshot"` + A description of what the response format is for, used by the model to + determine how to respond in the format. - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `strict: optional boolean` - - `"screenshot"` + 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). - - `Scroll object { scroll_x, scroll_y, type, 3 more }` +### Beta Response Function Call Arguments Delta Event - A scroll action. +- `BetaResponseFunctionCallArgumentsDeltaEvent object { delta, item_id, output_index, 3 more }` - - `scroll_x: number` + Emitted when there is a partial function-call arguments delta. - The horizontal scroll distance. + - `delta: string` - - `scroll_y: number` + The function-call arguments delta that is added. - The vertical scroll distance. + - `item_id: string` - - `type: "scroll"` + The ID of the output item that the function-call arguments delta is added to. - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `output_index: number` - - `"scroll"` + The index of the output item that the function-call arguments delta is added to. - - `x: number` + - `sequence_number: number` - The x-coordinate where the scroll occurred. + The sequence number of this event. - - `y: number` + - `type: "response.function_call_arguments.delta"` - The y-coordinate where the scroll occurred. + The type of the event. Always `response.function_call_arguments.delta`. - - `keys: optional array of string` + - `"response.function_call_arguments.delta"` - The keys being held while scrolling. + - `agent: optional object { agent_name }` - - `Type object { text, type }` + The agent that owns this multi-agent streaming event. - An action to type in text. + - `agent_name: string` - - `text: string` + The canonical name of the agent that produced this item. - The text to type. +### Beta Response Function Call Arguments Done Event - - `type: "type"` +- `BetaResponseFunctionCallArgumentsDoneEvent object { arguments, item_id, name, 4 more }` - Specifies the event type. For a type action, this property is always set to `type`. + Emitted when function-call arguments are finalized. - - `"type"` + - `arguments: string` - - `Wait object { type }` + The function-call arguments. - A wait action. + - `item_id: string` - - `type: "wait"` + The ID of the item. - Specifies the event type. For a wait action, this property is always set to `wait`. + - `name: string` - - `"wait"` + The name of the function that was called. - - `actions: optional BetaComputerActionList` + - `output_index: number` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + The index of the output item. - - `Click object { button, type, x, 2 more }` + - `sequence_number: number` - A click action. + The sequence number of this event. - - `DoubleClick object { keys, type, x, y }` + - `type: "response.function_call_arguments.done"` - A double click action. + - `"response.function_call_arguments.done"` - - `Drag object { path, type, keys }` + - `agent: optional object { agent_name }` - A drag action. + The agent that owns this multi-agent streaming event. - - `Keypress object { keys, type }` + - `agent_name: string` - A collection of keypresses the model would like to perform. + The canonical name of the agent that produced this item. - - `Move object { type, x, y, keys }` +### Beta Response Function Shell Call Output Content - A mouse move action. +- `BetaResponseFunctionShellCallOutputContent object { outcome, stderr, stdout }` - - `Screenshot object { type }` + Captured stdout and stderr for a portion of a shell tool call output. - A screenshot action. + - `outcome: object { type } or object { exit_code, type }` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + The exit or timeout outcome associated with this shell call. - A scroll action. + - `Timeout object { type }` - - `Type object { text, type }` + Indicates that the shell call exceeded its configured time limit. - An action to type in text. + - `type: "timeout"` - - `Wait object { type }` + The outcome type. Always `timeout`. - A wait action. + - `"timeout"` - - `agent: optional object { agent_name }` + - `Exit object { exit_code, type }` - The agent that produced this item. + Indicates that the shell commands finished and returned an exit code. - - `agent_name: string` + - `exit_code: number` - The canonical name of the agent that produced this item. + The exit code returned by the shell process. - - `ComputerCallOutput object { call_id, output, type, 4 more }` + - `type: "exit"` - The output of a computer tool call. + The outcome type. Always `exit`. - - `call_id: string` + - `"exit"` - The ID of the computer tool call that produced the output. + - `stderr: string` - - `output: BetaResponseComputerToolCallOutputScreenshot` + Captured stderr output for the shell call. - A computer screenshot image used with the computer use tool. + - `stdout: string` - - `type: "computer_screenshot"` + Captured stdout output for the shell call. - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. +### Beta Response Image Gen Call Completed Event - - `"computer_screenshot"` +- `BetaResponseImageGenCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` - - `file_id: optional string` + Emitted when an image generation tool call has completed and the final image is available. - The identifier of an uploaded file that contains the screenshot. + - `item_id: string` - - `image_url: optional string` + The unique identifier of the image generation item being processed. - The URL of the screenshot image. + - `output_index: number` - - `type: "computer_call_output"` + The index of the output item in the response's output array. - The type of the computer tool call output. Always `computer_call_output`. + - `sequence_number: number` - - `"computer_call_output"` + The sequence number of this event. - - `id: optional string` + - `type: "response.image_generation_call.completed"` - The ID of the computer tool call output. + The type of the event. Always 'response.image_generation_call.completed'. - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `"response.image_generation_call.completed"` - The safety checks reported by the API that have been acknowledged by the developer. + - `agent: optional object { agent_name }` - - `id: string` + The agent that owns this multi-agent streaming event. - The ID of the pending safety check. + - `agent_name: string` - - `code: optional string` + The canonical name of the agent that produced this item. - The type of the pending safety check. +### Beta Response Image Gen Call Generating Event - - `message: optional string` +- `BetaResponseImageGenCallGeneratingEvent object { item_id, output_index, sequence_number, 2 more }` - Details about the pending safety check. + Emitted when an image generation tool call is actively generating an image (intermediate state). - - `agent: optional object { agent_name }` + - `item_id: string` - The agent that produced this item. + The unique identifier of the image generation item being processed. - - `agent_name: string` + - `output_index: number` - The canonical name of the agent that produced this item. + The index of the output item in the response's output array. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `sequence_number: number` - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + The sequence number of the image generation item being processed. - - `"in_progress"` + - `type: "response.image_generation_call.generating"` - - `"completed"` + The type of the event. Always 'response.image_generation_call.generating'. - - `"incomplete"` + - `"response.image_generation_call.generating"` - - `WebSearchCall object { id, action, status, 2 more }` + - `agent: optional object { agent_name }` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + The agent that owns this multi-agent streaming event. - - `id: string` + - `agent_name: string` - The unique ID of the web search tool call. + The canonical name of the agent that produced this item. - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` +### Beta Response Image Gen Call In Progress Event - 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). +- `BetaResponseImageGenCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` - - `Search object { type, queries, query, sources }` + Emitted when an image generation tool call is in progress. - Action type "search" - Performs a web search query. + - `item_id: string` - - `type: "search"` + The unique identifier of the image generation item being processed. - The action type. + - `output_index: number` - - `"search"` + The index of the output item in the response's output array. - - `queries: optional array of string` + - `sequence_number: number` - The search queries. + The sequence number of the image generation item being processed. - - `query: optional string` + - `type: "response.image_generation_call.in_progress"` - The search query. + The type of the event. Always 'response.image_generation_call.in_progress'. - - `sources: optional array of object { type, url }` + - `"response.image_generation_call.in_progress"` - The sources used in the search. + - `agent: optional object { agent_name }` - - `type: "url"` + The agent that owns this multi-agent streaming event. - The type of source. Always `url`. + - `agent_name: string` - - `"url"` + The canonical name of the agent that produced this item. - - `url: string` +### Beta Response Image Gen Call Partial Image Event - The URL of the source. +- `BetaResponseImageGenCallPartialImageEvent object { item_id, output_index, partial_image_b64, 4 more }` - - `OpenPage object { type, url }` + Emitted when a partial image is available during image generation streaming. - Action type "open_page" - Opens a specific URL from search results. + - `item_id: string` - - `type: "open_page"` + The unique identifier of the image generation item being processed. - The action type. + - `output_index: number` - - `"open_page"` + The index of the output item in the response's output array. - - `url: optional string` + - `partial_image_b64: string` - The URL opened by the model. + Base64-encoded partial image data, suitable for rendering as an image. - - `FindInPage object { pattern, type, url }` + - `partial_image_index: number` - Action type "find_in_page": Searches for a pattern within a loaded page. + 0-based index for the partial image (backend is 1-based, but this is 0-based for the user). - - `pattern: string` + - `sequence_number: number` - The pattern or text to search for within the page. + The sequence number of the image generation item being processed. - - `type: "find_in_page"` + - `type: "response.image_generation_call.partial_image"` - The action type. + The type of the event. Always 'response.image_generation_call.partial_image'. - - `"find_in_page"` + - `"response.image_generation_call.partial_image"` - - `url: string` + - `agent: optional object { agent_name }` - The URL of the page searched for the pattern. + The agent that owns this multi-agent streaming event. - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `agent_name: string` - The status of the web search tool call. + The canonical name of the agent that produced this item. - - `"in_progress"` +### Beta Response In Progress Event - - `"searching"` +- `BetaResponseInProgressEvent object { response, sequence_number, type, agent }` - - `"completed"` + Emitted when the response is in progress. - - `"failed"` + - `response: BetaResponse` - - `type: "web_search_call"` + The response that is in progress. - The type of the web search tool call. Always `web_search_call`. + - `id: string` - - `"web_search_call"` + Unique identifier for this Response. - - `agent: optional object { agent_name }` + - `created_at: number` - The agent that produced this item. + Unix timestamp (in seconds) of when this Response was created. - - `agent_name: string` + - `error: BetaResponseError` - The canonical name of the agent that produced this item. + An error object returned when the model fails to generate a Response. - - `FunctionCall object { arguments, call_id, name, 6 more }` + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 16 more` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + The error code for the response. - - `arguments: string` + - `"server_error"` - A JSON string of the arguments to pass to the function. + - `"rate_limit_exceeded"` - - `call_id: string` + - `"invalid_prompt"` - The unique ID of the function tool call generated by the model. + - `"bio_policy"` - - `name: string` + - `"vector_store_timeout"` - The name of the function to run. + - `"invalid_image"` - - `type: "function_call"` + - `"invalid_image_format"` - The type of the function tool call. Always `function_call`. + - `"invalid_base64_image"` - - `"function_call"` + - `"invalid_image_url"` - - `id: optional string` + - `"image_too_large"` - The unique ID of the function tool call. + - `"image_too_small"` - - `agent: optional object { agent_name }` + - `"image_parse_error"` - The agent that produced this item. + - `"image_content_policy_violation"` - - `agent_name: string` + - `"invalid_image_mode"` - The canonical name of the agent that produced this item. + - `"image_file_too_large"` - - `caller: optional object { type } or object { caller_id, type }` + - `"unsupported_image_media_type"` - The execution context that produced this tool call. + - `"empty_image_file"` - - `Direct object { type }` + - `"failed_to_download_image"` - - `type: "direct"` + - `"image_file_not_found"` - - `"direct"` + - `message: string` - - `Program object { caller_id, type }` + A human-readable description of the error. - - `caller_id: string` + - `incomplete_details: object { reason }` - The call ID of the program item that produced this tool call. + Details about why the response is incomplete. - - `type: "program"` + - `reason: optional "max_output_tokens" or "content_filter"` - - `"program"` + The reason why the response is incomplete. - - `namespace: optional string` + - `"max_output_tokens"` - The namespace of the function to run. + - `"content_filter"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `instructions: string or array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + A system (or developer) message inserted into the model's context. - - `"in_progress"` + 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. - - `"completed"` + - `string` - - `"incomplete"` + A text input to the model, equivalent to a text input with the + `developer` role. - - `FunctionCallOutput object { call_id, output, type, 4 more }` + - `InputItemList = array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` - The output of a function tool call. + A list of one or many input items to the model, containing + different content types. - - `call_id: string` + - `BetaEasyInputMessage object { content, role, phase, type }` - The unique ID of the function tool call generated by the model. + 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. - - `output: string or BetaResponseFunctionCallOutputItemList` + - `content: string or BetaResponseInputMessageContentList` - Text, image, or file output of the function tool call. + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `string` + - `TextInput = string` - A JSON string of the output of the function tool call. + A text input to the model. - - `BetaResponseFunctionCallOutputItemList = array of BetaResponseFunctionCallOutputItem` + - `BetaResponseInputMessageContentList = array of BetaResponseInputContent` - 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 }` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` A text input to the model. @@ -101149,17 +100796,11 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"explicit"` - - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - - `type: "input_image"` - - 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`. @@ -101171,6 +100812,12 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"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. @@ -101189,7 +100836,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"explicit"` - - `BetaResponseInputFileContent object { type, detail, file_data, 4 more }` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` A file input to the model. @@ -101211,7 +100858,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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` @@ -101235,149 +100882,55 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"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](https://platform.openai.com/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 }` + - `role: "user" or "assistant" or "system" or "developer"` - The agent that produced this item. + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - - `agent_name: string` + - `"user"` - The canonical name of the agent that produced this item. + - `"assistant"` - - `MultiAgentCall object { action, arguments, call_id, 3 more }` + - `"system"` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `"developer"` - The multi-agent action that was executed. + - `phase: optional "commentary" or "final_answer"` - - `"spawn_agent"` + 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. - - `"interrupt_agent"` + - `"commentary"` - - `"list_agents"` + - `"final_answer"` - - `"send_message"` + - `type: optional "message"` - - `"followup_task"` + The type of the message input. Always `message`. - - `"wait_agent"` + - `"message"` - - `arguments: string` + - `Message object { content, role, agent, 2 more }` - The action arguments as a JSON 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. - - `call_id: string` + - `content: BetaResponseInputMessageContentList` - The unique ID linking this call to its output. + A list of one or many input items to the model, containing different content + types. - - `type: "multi_agent_call"` + - `role: "user" or "system" or "developer"` - The item type. Always `multi_agent_call`. + The role of the message input. One of `user`, `system`, or `developer`. - - `"multi_agent_call"` + - `"user"` - - `id: optional string` + - `"system"` - The unique ID of this multi-agent call. + - `"developer"` - `agent: optional object { agent_name }` @@ -101387,47 +100940,46 @@ 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` + - `status: optional "in_progress" or "completed" or "incomplete"` - The multi-agent action that produced this result. + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"spawn_agent"` + - `"in_progress"` - - `"interrupt_agent"` + - `"completed"` - - `"list_agents"` + - `"incomplete"` - - `"send_message"` + - `type: optional "message"` - - `"followup_task"` + The type of the message input. Always set to `message`. - - `"wait_agent"` + - `"message"` - - `call_id: string` + - `BetaResponseOutputMessage object { id, content, role, 4 more }` - The unique ID of the multi-agent call. + An output message from the model. - - `output: array of object { text, type, annotations }` + - `id: string` - Text output returned by the multi-agent action. + The unique ID of the output message. - - `text: string` + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - The text content. + The content of the output message. - - `type: "output_text"` + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - The content type. Always `output_text`. + A text output from the model. - - `"output_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 }` - - `annotations: optional array of object { file_id, filename, index, type } or array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` + The annotations of the text output. - Citations associated with the text content. + - `FileCitation object { file_id, filename, index, type }` - - `array of object { file_id, filename, index, type }` + A citation to a file. - `file_id: string` @@ -101443,293 +100995,218 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "file_citation"` - The citation type. Always `file_citation`. + The type of the file citation. Always `file_citation`. - `"file_citation"` - - `array of object { end_index, start_index, title, 2 more }` + - `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 citation in the message. + The index of the last character of the URL citation in the message. - `start_index: number` - The index of the first character of the citation in the message. + The index of the first character of the URL citation in the message. - `title: string` - The title of the cited resource. + The title of the web resource. - `type: "url_citation"` - The citation type. Always `url_citation`. + The type of the URL citation. Always `url_citation`. - `"url_citation"` - `url: string` - The URL of the cited resource. - - - `array of object { container_id, end_index, file_id, 3 more }` - - - `container_id: string` - - The ID of the container. + The URL of the web resource. - - `end_index: number` + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - The index of the last character of the citation in the message. + A citation for a container file used to generate a model response. - - `file_id: string` + - `container_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"` + - `end_index: number` - - `status: optional "in_progress" or "completed" or "incomplete"` + The index of the last character of the container file citation in the message. - The status of the tool search call. + - `file_id: string` - - `"in_progress"` + The ID of the file. - - `"completed"` + - `filename: string` - - `"incomplete"` + The filename of the container file cited. - - `ToolSearchOutput object { tools, type, id, 4 more }` + - `start_index: 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` + The index of the first character of the container file citation in the message. - The loaded tool definitions returned by the tool search output. + - `type: "container_file_citation"` - - `Function object { name, parameters, strict, 5 more }` + The type of the container file citation. Always `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). + - `"container_file_citation"` - - `name: string` + - `FilePath object { file_id, index, type }` - The name of the function to call. + A path to a file. - - `parameters: map[unknown]` + - `file_id: string` - A JSON schema object describing the parameters of the function. + The ID of the file. - - `strict: boolean` + - `index: number` - Whether strict parameter validation is enforced for this function tool. + The index of the file in the list of files. - - `type: "function"` + - `type: "file_path"` - The type of the function tool. Always `function`. + The type of the file path. Always `file_path`. - - `"function"` + - `"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` - - `defer_loading: optional boolean` + - `top_logprobs: array of object { token, bytes, logprob }` - Whether this function is deferred and loaded via tool search. + - `token: string` - - `description: optional string` + - `bytes: array of number` - A description of the function. Used by the model to determine whether or not to call the function. + - `logprob: number` - - `output_schema: optional map[unknown]` + - `text: string` - A JSON schema object describing the JSON value encoded in string outputs for this function. + The text output from the model. - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + - `type: "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). + The type of the output text. Always `output_text`. - - `type: "file_search"` + - `"output_text"` - The type of the file search tool. Always `file_search`. + - `BetaResponseOutputRefusal object { refusal, type }` - - `"file_search"` + A refusal from the model. - - `vector_store_ids: array of string` + - `refusal: string` - The IDs of the vector stores to search. + The refusal explanation from the model. - - `filters: optional object { key, type, value } or object { filters, type }` + - `type: "refusal"` - A filter to apply. + The type of the refusal. Always `refusal`. - - `ComparisonFilter object { key, type, value }` + - `"refusal"` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `role: "assistant"` - - `key: string` + The role of the output message. Always `assistant`. - The key to compare against the value. + - `"assistant"` - - `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 message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `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: "message"` - - `"gte"` + The type of the output message. Always `message`. - - `"lt"` + - `"message"` - - `"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. + - `phase: optional "commentary" or "final_answer"` - - `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. - - `number` + - `"commentary"` - - `boolean` + - `"final_answer"` - - `array of string or number` + - `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. - - `number` + - `id: string` - - `CompoundFilter object { filters, type }` + The unique ID of the file search tool call. - Combine multiple filters using `and` or `or`. + - `queries: array of string` - - `filters: array of object { key, type, value } or unknown` + The queries used to search for files. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `status: "in_progress" or "searching" or "completed" or 2 more` - - `ComparisonFilter object { key, type, value }` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `"in_progress"` - - `key: string` + - `"searching"` - The key to compare against the value. + - `"completed"` - - `type: "eq" or "ne" or "gt" or 5 more` + - `"incomplete"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `"failed"` - - `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: "file_search_call"` - - `"eq"` + The type of the file search tool call. Always `file_search_call`. - - `"ne"` + - `"file_search_call"` - - `"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"` + - `results: optional array of object { attributes, file_id, filename, 2 more }` - - `"nin"` + The results of the file search tool call. - - `value: string or number or boolean or array of string or number` + - `attributes: optional map[string or number or boolean]` - The value to compare against the attribute key; supports string, number, or boolean types. + 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` @@ -101737,1003 +101214,984 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `boolean` - - `array of string or number` + - `file_id: optional string` - - `string` + The unique ID of the file. - - `number` + - `filename: optional string` - - `unknown` + The name of the file. - - `type: "and" or "or"` + - `score: optional number` - Type of operation: `and` or `or`. + The relevance score of the file - a value between 0 and 1. - - `"and"` + - `text: optional string` - - `"or"` + The text that was retrieved from the file. - - `max_num_results: optional number` + - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `id: string` - Ranking options for search. + The unique ID of the computer call. - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `call_id: string` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + An identifier used when responding to the tool call with output. - - `embedding_weight: number` + - `pending_safety_checks: array of object { id, code, message }` - The weight of the embedding in the reciprocal ranking fusion. + The pending safety checks for the computer call. - - `text_weight: number` + - `id: string` - The weight of the text in the reciprocal ranking fusion. + The ID of the pending safety check. - - `ranker: optional "auto" or "default-2024-11-15"` + - `code: optional string` - The ranker to use for the file search. + The type of the pending safety check. - - `"auto"` + - `message: optional string` - - `"default-2024-11-15"` + Details about the pending safety check. - - `score_threshold: optional number` + - `status: "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`. Populated when items are returned via API. - - `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`. + - `type: "computer_call"` - - `"computer"` + The type of the computer call. Always `computer_call`. - - `ComputerUsePreview object { display_height, display_width, environment, type }` + - `"computer_call"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `action: optional BetaComputerAction` - - `display_height: number` + A click action. - The height of the computer display. + - `Click object { button, type, x, 2 more }` - - `display_width: number` + A click action. - The width of the computer display. + - `button: "left" or "right" or "wheel" or 2 more` - - `environment: "windows" or "mac" or "linux" or 2 more` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - The type of computer environment to control. + - `"left"` - - `"windows"` + - `"right"` - - `"mac"` + - `"wheel"` - - `"linux"` + - `"back"` - - `"ubuntu"` + - `"forward"` - - `"browser"` + - `type: "click"` - - `type: "computer_use_preview"` + Specifies the event type. For a click action, this property is always `click`. - The type of the computer use tool. Always `computer_use_preview`. + - `"click"` - - `"computer_use_preview"` + - `x: number` - - `WebSearch object { type, filters, search_context_size, user_location }` + The x-coordinate where the click occurred. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `y: number` - - `type: "web_search" or "web_search_2025_08_26"` + The y-coordinate where the click occurred. - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `keys: optional array of string` - - `"web_search"` + The keys being held while clicking. - - `"web_search_2025_08_26"` + - `DoubleClick object { keys, type, x, y }` - - `filters: optional object { allowed_domains }` + A double click action. - Filters for the search. + - `keys: array of string` - - `allowed_domains: optional array of string` + The keys being held while double-clicking. - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `type: "double_click"` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `search_context_size: optional "low" or "medium" or "high"` + - `"double_click"` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `x: number` - - `"low"` + The x-coordinate where the double click occurred. - - `"medium"` + - `y: number` - - `"high"` + The y-coordinate where the double click occurred. - - `user_location: optional object { city, country, region, 2 more }` + - `Drag object { path, type, keys }` - The approximate location of the user. + A drag action. - - `city: optional string` + - `path: array of object { x, y }` - Free text input for the city of the user, e.g. `San Francisco`. + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `country: optional string` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `x: number` - - `region: optional string` + The x-coordinate. - Free text input for the region of the user, e.g. `California`. + - `y: number` - - `timezone: optional string` + The y-coordinate. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `type: "drag"` - - `type: optional "approximate"` + Specifies the event type. For a drag action, this property is always set to `drag`. - The type of location approximation. Always `approximate`. + - `"drag"` - - `"approximate"` + - `keys: optional array of string` - - `Mcp object { server_label, type, allowed_callers, 9 more }` + The keys being held while dragging the mouse. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `Keypress object { keys, type }` - - `server_label: string` + A collection of keypresses the model would like to perform. - A label for this MCP server, used to identify it in tool calls. + - `keys: array of string` - - `type: "mcp"` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - The type of the MCP tool. Always `mcp`. + - `type: "keypress"` - - `"mcp"` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"keypress"` - The tool invocation context(s). + - `Move object { type, x, y, keys }` - - `"direct"` + A mouse move action. - - `"programmatic"` + - `type: "move"` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + Specifies the event type. For a move action, this property is always set to `move`. - List of allowed tool names or a filter object. + - `"move"` - - `McpAllowedTools = array of string` + - `x: number` - A string array of allowed tool names + The x-coordinate to move to. - - `McpToolFilter object { read_only, tool_names }` + - `y: number` - A filter object to specify which tools are allowed. + The y-coordinate to move to. - - `read_only: optional boolean` + - `keys: 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. + The keys being held while moving the mouse. - - `tool_names: optional array of string` + - `Screenshot object { type }` - List of allowed tool names. + A screenshot action. - - `authorization: optional string` + - `type: "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. + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + - `"screenshot"` - 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - Currently supported `connector_id` values are: + A scroll action. - - 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` + - `scroll_x: number` - - `"connector_dropbox"` + The horizontal scroll distance. - - `"connector_gmail"` + - `scroll_y: number` - - `"connector_googlecalendar"` + The vertical scroll distance. - - `"connector_googledrive"` + - `type: "scroll"` - - `"connector_microsoftteams"` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `"connector_outlookcalendar"` + - `"scroll"` - - `"connector_outlookemail"` + - `x: number` - - `"connector_sharepoint"` + The x-coordinate where the scroll occurred. - - `defer_loading: optional boolean` + - `y: number` - Whether this MCP tool is deferred and discovered via tool search. + The y-coordinate where the scroll occurred. - - `headers: optional map[string]` + - `keys: optional array of string` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + The keys being held while scrolling. - - `require_approval: optional object { always, never } or "always" or "never"` + - `Type object { text, type }` - Specify which of the MCP server's tools require approval. + An action to type in text. - - `McpToolApprovalFilter object { always, never }` + - `text: string` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + The text to type. - - `always: optional object { read_only, tool_names }` + - `type: "type"` - A filter object to specify which tools are allowed. + Specifies the event type. For a type action, this property is always set to `type`. - - `read_only: optional boolean` + - `"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. + - `Wait object { type }` - - `tool_names: optional array of string` + A wait action. - List of allowed tool names. + - `type: "wait"` - - `never: optional object { read_only, tool_names }` + Specifies the event type. For a wait action, this property is always set to `wait`. - A filter object to specify which tools are allowed. + - `"wait"` - - `read_only: optional boolean` + - `actions: optional BetaComputerActionList` - 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. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `tool_names: optional array of string` + - `Click object { button, type, x, 2 more }` - List of allowed tool names. + A click action. - - `McpToolApprovalSetting = "always" or "never"` + - `DoubleClick object { keys, type, x, y }` - 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 double click action. - - `"always"` + - `Drag object { path, type, keys }` - - `"never"` + A drag action. - - `server_description: optional string` + - `Keypress object { keys, type }` - Optional description of the MCP server, used to provide more context. + A collection of keypresses the model would like to perform. - - `server_url: optional string` + - `Move object { type, x, y, keys }` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + A mouse move action. - - `tunnel_id: optional string` + - `Screenshot 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. + A screenshot action. - - `CodeInterpreter object { container, type, allowed_callers }` + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - A tool that runs Python code to help generate a response to a prompt. + A scroll action. - - `container: string or object { type, file_ids, memory_limit, network_policy }` + - `Type object { text, type }` - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + An action to type in text. - - `string` + - `Wait object { type }` - The container ID. + A wait action. - - `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"` + - `ComputerCallOutput object { call_id, output, type, 4 more }` - - `file_ids: optional array of string` + The output of a computer tool call. - 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` - - `type: "disabled"` + The URL of the screenshot image. - Disable outbound network access. Always `disabled`. + - `type: "computer_call_output"` - - `"disabled"` + The type of the computer tool call output. Always `computer_call_output`. - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `"computer_call_output"` - - `allowed_domains: array of string` + - `id: optional string` - A list of allowed domains when type is `allowlist`. + The ID of the computer tool call output. - - `type: "allowlist"` + - `acknowledged_safety_checks: optional array of object { id, code, message }` - Allow outbound network access only to specified domains. Always `allowlist`. + The safety checks reported by the API that have been acknowledged by the developer. - - `"allowlist"` + - `id: string` - - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` + The ID of the pending safety check. - Optional domain-scoped secrets for allowlisted domains. + - `code: optional string` - - `domain: string` + The type of the pending safety check. - The domain associated with the secret. + - `message: optional string` - - `name: string` + Details about the pending safety check. - The name of the secret to inject for the domain. + - `agent: optional object { agent_name }` - - `value: string` + The agent that produced this item. - The secret value to inject for the domain. + - `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`. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"code_interpreter"` + 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"` + - `WebSearchCall object { id, action, status, 2 more }` - - `ProgrammaticToolCalling object { type }` + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. - - `type: "programmatic_tool_calling"` + - `id: string` - The type of the tool. Always `programmatic_tool_calling`. + The unique ID of the web search tool call. - - `"programmatic_tool_calling"` + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - - `ImageGeneration object { type, action, background, 9 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 that generates images using the GPT image models. + - `Search object { type, queries, query, sources }` - - `type: "image_generation"` + Action type "search" - Performs a web search query. - The type of the image generation tool. Always `image_generation`. + - `type: "search"` - - `"image_generation"` + The action type. - - `action: optional "generate" or "edit" or "auto"` + - `"search"` - Whether to generate a new image or edit an existing image. Default: `auto`. + - `queries: optional array of string` - - `"generate"` + The search queries. - - `"edit"` + - `query: optional string` - - `"auto"` + The search query. - - `background: optional "transparent" or "opaque" or "auto"` + - `sources: optional array of object { type, url }` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + The sources used in the search. - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + - `type: "url"` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + The type of source. Always `url`. - - `"transparent"` + - `"url"` - - `"opaque"` + - `url: string` - - `"auto"` + The URL of the source. - - `input_fidelity: optional "high" or "low"` + - `OpenPage object { type, url }` - 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 type "open_page" - Opens a specific URL from search results. - - `"high"` + - `type: "open_page"` - - `"low"` + The action type. - - `input_image_mask: optional object { file_id, image_url }` + - `"open_page"` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `url: optional string` - - `file_id: optional string` + The URL opened by the model. - File ID for the mask image. + - `FindInPage object { pattern, type, url }` - - `image_url: optional string` + Action type "find_in_page": Searches for a pattern within a loaded page. - Base64-encoded mask image. + - `pattern: string` - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + The pattern or text to search for within the page. - The image generation model to use. Default: `gpt-image-1`. + - `type: "find_in_page"` - - `string` + The action type. - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `"find_in_page"` - The image generation model to use. Default: `gpt-image-1`. + - `url: string` - - `"gpt-image-1"` + The URL of the page searched for the pattern. - - `"gpt-image-1-mini"` + - `status: "in_progress" or "searching" or "completed" or "failed"` - - `"gpt-image-2"` + The status of the web search tool call. - - `"gpt-image-2-2026-04-21"` + - `"in_progress"` - - `"gpt-image-1.5"` + - `"searching"` - - `"chatgpt-image-latest"` + - `"completed"` - - `moderation: optional "auto" or "low"` + - `"failed"` - Moderation level for the generated image. Default: `auto`. + - `type: "web_search_call"` - - `"auto"` + The type of the web search tool call. Always `web_search_call`. - - `"low"` + - `"web_search_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"` + - `FunctionCall object { arguments, call_id, name, 6 more }` - - `"webp"` + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. - - `"jpeg"` + - `arguments: string` - - `partial_images: optional number` + A JSON string of the arguments to pass to the function. - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `call_id: string` - - `quality: optional "low" or "medium" or "high" or "auto"` + The unique ID of the function tool call generated by the model. - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `name: string` - - `"low"` + The name of the function to run. - - `"medium"` + - `type: "function_call"` - - `"high"` + The type of the function tool call. Always `function_call`. - - `"auto"` + - `"function_call"` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `id: optional string` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + The unique ID of the function tool call. - - `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"` + - `caller: optional object { type } or object { caller_id, type }` - - `"1536x1024"` + The execution context that produced this tool call. - - `"auto"` + - `Direct object { type }` - - `LocalShell object { type }` + - `type: "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. + - `"program"` - - `type: "shell"` + - `namespace: optional string` - The type of the shell tool. Always `shell`. + The namespace of the function to run. - - `"shell"` + - `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"` - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + - `FunctionCallOutput object { call_id, output, type, 4 more }` - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + The output of a function tool call. - - `type: "container_auto"` + - `call_id: string` - Automatically creates a container for this request + The unique ID of the function tool call generated by the model. - - `"container_auto"` + - `output: string or array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` - - `file_ids: optional array of string` + Text, image, or file output of the function tool call. - An optional list of uploaded files to make available to your code. + - `string` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + A JSON string of the output of the function tool call. - The memory limit for the container. + - `array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` - - `"1g"` + An array of content outputs (text, image, file) for the function tool call. - - `"4g"` + - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` - - `"16g"` + A text input to the model. - - `"64g"` + - `text: string` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + The text input to the model. - Network access policy for the container. + - `type: "input_text"` - - `BetaContainerNetworkPolicyDisabled object { type }` + The type of the input item. Always `input_text`. - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `"input_text"` - - `skills: optional array of BetaSkillReference or BetaInlineSkill` + - `prompt_cache_breakpoint: optional object { mode }` - An optional list of skills referenced by id or inline data. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `BetaSkillReference object { skill_id, type, version }` + - `mode: "explicit"` - - `skill_id: string` + The breakpoint mode. Always `explicit`. - The ID of the referenced skill. + - `"explicit"` - - `type: "skill_reference"` + - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` - References a skill created with the /v1/skills endpoint. + An image input to the model. Learn about [image inputs](/docs/guides/vision) - - `"skill_reference"` + - `type: "input_image"` - - `version: optional string` + The type of the input item. Always `input_image`. - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `"input_image"` - - `BetaInlineSkill object { description, name, source, type }` + - `detail: optional "low" or "high" or "auto" or "original"` - - `description: string` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The description of the skill. + - `"low"` - - `name: string` + - `"high"` - The name of the skill. + - `"auto"` - - `source: BetaInlineSkillSource` + - `"original"` - Inline skill payload + - `file_id: optional string` - - `data: string` + The ID of the file to be sent to the model. - Base64-encoded skill zip bundle. + - `image_url: optional string` - - `media_type: "application/zip"` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - The media type of the inline skill payload. Must be `application/zip`. + - `prompt_cache_breakpoint: optional object { mode }` - - `"application/zip"` + Marks the exact end of a reusable 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: "base64"` + - `mode: "explicit"` - The type of the inline skill source. Must be `base64`. + The breakpoint mode. Always `explicit`. - - `"base64"` + - `"explicit"` - - `type: "inline"` + - `BetaResponseInputFileContent object { type, detail, file_data, 4 more }` - Defines an inline skill for this request. + A file input to the model. - - `"inline"` + - `type: "input_file"` - - `BetaLocalEnvironment object { type, skills }` + The type of the input item. Always `input_file`. - - `type: "local"` + - `"input_file"` - Use a local computer environment. + - `detail: optional "auto" or "low" or "high"` - - `"local"` + 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`. - - `skills: optional array of BetaLocalSkill` + - `"auto"` - An optional list of skills. + - `"low"` - - `description: string` + - `"high"` - The description of the skill. + - `file_data: optional string` - - `name: string` + The base64-encoded data of the file to be sent to the model. - The name of the skill. + - `file_id: optional string` - - `path: string` + The ID of the file to be sent to the model. - The path to the directory containing the skill. + - `file_url: optional string` - - `BetaContainerReference object { container_id, type }` + The URL of the file to be sent to the model. - - `container_id: string` + - `filename: optional string` - The ID of the referenced container. + The name of the file to be sent to the model. - - `type: "container_reference"` + - `prompt_cache_breakpoint: optional object { mode }` - References a container created with the /v1/containers endpoint + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `"container_reference"` + - `mode: "explicit"` - - `Custom object { name, type, allowed_callers, 3 more }` + The breakpoint mode. Always `explicit`. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `"explicit"` - - `name: string` + - `type: "function_call_output"` - The name of the custom tool, used to identify it in tool calls. + The type of the function tool call output. Always `function_call_output`. - - `type: "custom"` + - `"function_call_output"` - The type of the custom tool. Always `custom`. + - `id: optional string` - - `"custom"` + The unique ID of the function tool call output. Populated when this item is returned via API. - - `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 }` + The caller type. Always `direct`. - The input format for the custom tool. Default is unconstrained text. + - `"direct"` - - `Text object { type }` + - `Program object { caller_id, type }` - Unconstrained free-form text. + - `caller_id: string` - - `type: "text"` + The call ID of the program item that produced this tool call. - Unconstrained text format. Always `text`. + - `type: "program"` - - `"text"` + The caller type. Always `program`. - - `Grammar object { definition, syntax, type }` + - `"program"` - A grammar defined by the user. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `definition: string` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - The grammar definition. + - `"in_progress"` - - `syntax: "lark" or "regex"` + - `"completed"` - The syntax of the grammar definition. One of `lark` or `regex`. + - `"incomplete"` - - `"lark"` + - `AgentMessage object { author, content, recipient, 3 more }` - - `"regex"` + A message routed between agents. - - `type: "grammar"` + - `author: string` - Grammar format. Always `grammar`. + The sending agent identity. - - `"grammar"` + - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` - - `Namespace object { description, name, tools, type }` + Plaintext, image, or encrypted content sent between agents. - Groups function/custom tools under a shared namespace. + - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` - - `description: string` + A text input to the model. - A description of the namespace shown to the model. + - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` - - `name: string` + An image input to the model. Learn about [image inputs](/docs/guides/vision) - The namespace name used in tool calls (for example, `crm`). + - `EncryptedContent object { encrypted_content, type }` - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - The function/custom tools available inside this namespace. + - `encrypted_content: string` - - `Function object { name, type, allowed_callers, 5 more }` + Opaque encrypted content. - - `name: string` + - `type: "encrypted_content"` - - `type: "function"` + The type of the input item. Always `encrypted_content`. - - `"function"` + - `"encrypted_content"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `recipient: string` - The tool invocation context(s). + The destination agent identity. - - `"direct"` + - `type: "agent_message"` - - `"programmatic"` + The item type. Always `agent_message`. - - `defer_loading: optional boolean` + - `"agent_message"` - Whether this function should be deferred and discovered via tool search. + - `id: optional string` - - `description: optional string` + The unique ID of this agent message item. - - `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. + - `MultiAgentCall object { action, arguments, call_id, 3 more }` - - `Custom object { name, type, allowed_callers, 3 more }` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The multi-agent action that was executed. - - `name: string` + - `"spawn_agent"` - The name of the custom tool, used to identify it in tool calls. + - `"interrupt_agent"` - - `type: "custom"` + - `"list_agents"` - The type of the custom tool. Always `custom`. + - `"send_message"` - - `"custom"` + - `"followup_task"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"wait_agent"` - The tool invocation context(s). + - `arguments: string` - - `"direct"` + The action arguments as a JSON string. - - `"programmatic"` + - `call_id: string` - - `defer_loading: optional boolean` + The unique ID linking this call to its output. - Whether this tool should be deferred and discovered via tool search. + - `type: "multi_agent_call"` - - `description: optional string` + The item type. Always `multi_agent_call`. - Optional description of the custom tool, used to provide more context. + - `"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. - - `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 }` + - `MultiAgentCallOutput object { action, call_id, output, 3 more }` - Unconstrained free-form text. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `type: "text"` + The multi-agent action that produced this result. - Unconstrained text format. Always `text`. + - `"spawn_agent"` - - `"text"` + - `"interrupt_agent"` - - `Grammar object { definition, syntax, type }` + - `"list_agents"` - A grammar defined by the user. + - `"send_message"` - - `definition: string` + - `"followup_task"` - The grammar definition. + - `"wait_agent"` - - `syntax: "lark" or "regex"` + - `call_id: string` - The syntax of the grammar definition. One of `lark` or `regex`. + The unique ID of the multi-agent call. - - `"lark"` + - `output: array of object { text, type, annotations }` - - `"regex"` + Text output returned by the multi-agent action. - - `type: "grammar"` + - `text: string` - Grammar format. Always `grammar`. + The text content. - - `"grammar"` + - `type: "output_text"` - - `type: "namespace"` + The content type. Always `output_text`. - The type of the tool. Always `namespace`. + - `"output_text"` - - `"namespace"` + - `annotations: optional array of object { file_id, filename, index, type } or array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` - - `ToolSearch object { type, description, execution, parameters }` + Citations associated with the text content. - Hosted or BYOT tool search configuration for deferred tools. + - `array of object { file_id, filename, index, type }` - - `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 file cited. - 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_citation"` - - `"server"` + The citation type. Always `file_citation`. - - `"client"` + - `"file_citation"` - - `parameters: optional unknown` + - `array of object { end_index, start_index, title, 2 more }` - Parameter schema for a client-executed tool search tool. + - `end_index: number` - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + The index of the last character of the citation in the 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). + - `start_index: number` - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + The index of the first character of the citation in the message. - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `title: string` - - `"web_search_preview"` + The title of the cited resource. - - `"web_search_preview_2025_03_11"` + - `type: "url_citation"` - - `search_content_types: optional array of "text" or "image"` + The citation type. Always `url_citation`. - - `"text"` + - `"url_citation"` - - `"image"` + - `url: string` - - `search_context_size: optional "low" or "medium" or "high"` + The URL of the cited resource. - 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. + - `array of object { container_id, end_index, file_id, 3 more }` - - `"low"` + - `container_id: string` - - `"medium"` + The ID of the container. - - `"high"` + - `end_index: number` - - `user_location: optional object { type, city, country, 2 more }` + The index of the last character of the citation in the message. - The user's location. + - `file_id: string` - - `type: "approximate"` + The ID of the container file. - The type of location approximation. Always `approximate`. + - `filename: string` - - `"approximate"` + 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 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 citation type. Always `container_file_citation`. - - `region: optional string` + - `"container_file_citation"` - Free text input for the region of the user, e.g. `California`. + - `type: "multi_agent_call_output"` - - `timezone: optional string` + The item type. Always `multi_agent_call_output`. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `"multi_agent_call_output"` - - `ApplyPatch object { type, allowed_callers }` + - `id: optional string` - Allows the assistant to create, delete, or update files using unified diffs. + The unique ID of this multi-agent call output. - - `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). + - `ToolSearchCall object { arguments, type, id, 4 more }` - - `"direct"` + - `arguments: unknown` - - `"programmatic"` + The arguments supplied to the tool search call. - - `type: "tool_search_output"` + - `type: "tool_search_call"` - The item type. Always `tool_search_output`. + The item type. Always `tool_search_call`. - - `"tool_search_output"` + - `"tool_search_call"` - `id: optional string` - The unique ID of this tool search output. + The unique ID of this tool search call. - `agent: optional object { agent_name }` @@ -102757,7 +102215,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `status: optional "in_progress" or "completed" or "incomplete"` - The status of the tool search output. + The status of the tool search call. - `"in_progress"` @@ -102765,17 +102223,11 @@ 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"` + - `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` - A list of additional tools made available at this item. + The loaded tool definitions returned by the tool search output. - `Function object { name, parameters, strict, 5 more }` @@ -103038,7 +102490,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-web-search). + [web search tool](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -103098,7 +102550,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -103150,7 +102602,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -103205,1597 +102657,726 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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"` - - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. - - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. - - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. - - - `"transparent"` - - - `"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-2" or 3 more` - - The image generation model to use. Default: `gpt-image-1`. - - - `string` - - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` - - The image generation model to use. Default: `gpt-image-1`. - - - `"gpt-image-1"` - - - `"gpt-image-1-mini"` - - - `"gpt-image-2"` - - - `"gpt-image-2-2026-04-21"` - - - `"gpt-image-1.5"` - - - `"chatgpt-image-latest"` - - - `moderation: optional "auto" or "low"` - - Moderation level for the generated image. Default: `auto`. - - - `"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](https://platform.openai.com/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](https://platform.openai.com/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 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](https://platform.openai.com/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 - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. - - - `status: optional "in_progress" or "completed" or "incomplete"` - - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `Compaction object { encrypted_content, type, id, agent }` - - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/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. + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `type: "local_shell_call_output"` + - `tool_names: optional array of string` - The type of the local shell tool call output. Always `local_shell_call_output`. + List of allowed tool names. - - `"local_shell_call_output"` + - `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` - - `status: optional "in_progress" or "completed" or "incomplete"` + List of allowed tool names. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `McpToolApprovalSetting = "always" or "never"` - - `"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. - - `"completed"` + - `"always"` - - `"incomplete"` + - `"never"` - - `ShellCall object { action, call_id, type, 5 more }` + - `server_description: optional string` - A tool representing a request to execute one or more shell commands. + Optional description of the MCP server, used to provide more context. - - `action: object { commands, max_output_length, timeout_ms }` + - `server_url: optional string` - The shell commands and limits that describe how to run the tool call. + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `commands: array of string` + - `tunnel_id: optional string` - Ordered shell commands for the execution environment to run. + 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. - - `max_output_length: optional number` + - `CodeInterpreter object { container, type, allowed_callers }` - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + A tool that runs Python code to help generate a response to a prompt. - - `timeout_ms: optional number` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - Maximum wall-clock time in milliseconds to allow the shell commands 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. - - `call_id: string` + - `string` - The unique ID of the shell tool call generated by the model. + The container ID. - - `type: "shell_call"` + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - The type of the item. Always `shell_call`. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `"shell_call"` + - `type: "auto"` - - `id: optional string` + Always `auto`. - The unique ID of the shell 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` - - `environment: optional BetaLocalEnvironment or BetaContainerReference` + A list of allowed domains when type is `allowlist`. - The environment to execute the shell commands in. + - `type: "allowlist"` - - `BetaLocalEnvironment object { type, skills }` + Allow outbound network access only to specified domains. Always `allowlist`. - - `BetaContainerReference object { container_id, type }` + - `"allowlist"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + Optional domain-scoped secrets for allowlisted domains. - - `"in_progress"` + - `domain: string` - - `"completed"` + The domain associated with the secret. - - `"incomplete"` + - `name: string` - - `ShellCallOutput object { call_id, output, type, 5 more }` + The name of the secret to inject for the domain. - The streamed output items emitted by a shell tool call. + - `value: string` - - `call_id: string` + The secret value to inject for the domain. - The unique ID of the shell tool call generated by the model. + - `type: "code_interpreter"` - - `output: array of BetaResponseFunctionShellCallOutputContent` + The type of the code interpreter tool. Always `code_interpreter`. - Captured chunks of stdout and stderr output, along with their associated outcomes. + - `"code_interpreter"` - - `outcome: object { type } or object { exit_code, type }` + - `allowed_callers: optional array of "direct" or "programmatic"` - The exit or timeout outcome associated with this shell call. + The tool invocation context(s). - - `Timeout object { type }` + - `"direct"` - Indicates that the shell call exceeded its configured time limit. + - `"programmatic"` - - `type: "timeout"` + - `ProgrammaticToolCalling object { type }` - The outcome type. Always `timeout`. + - `type: "programmatic_tool_calling"` - - `"timeout"` + The type of the tool. Always `programmatic_tool_calling`. - - `Exit object { exit_code, type }` + - `"programmatic_tool_calling"` - Indicates that the shell commands finished and returned an exit code. + - `ImageGeneration object { type, action, background, 9 more }` - - `exit_code: number` + A tool that generates images using the GPT image models. - The exit code returned by the shell process. + - `type: "image_generation"` - - `type: "exit"` + The type of the image generation tool. Always `image_generation`. - The outcome type. Always `exit`. + - `"image_generation"` - - `"exit"` + - `action: optional "generate" or "edit" or "auto"` - - `stderr: string` + Whether to generate a new image or edit an existing image. Default: `auto`. - Captured stderr output for the shell call. + - `"generate"` - - `stdout: string` + - `"edit"` - Captured stdout output for the shell call. + - `"auto"` - - `type: "shell_call_output"` + - `background: optional "transparent" or "opaque" or "auto"` - The type of the item. Always `shell_call_output`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - - `"shell_call_output"` + - `"transparent"` - - `id: optional string` + - `"opaque"` - The unique ID of the shell tool call output. Populated when this item is returned via API. + - `"auto"` - - `agent: optional object { agent_name }` + - `input_fidelity: optional "high" or "low"` - 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`. - - `agent_name: string` + - `"high"` - The canonical name of the agent that produced this item. + - `"low"` - - `caller: optional object { type } or object { caller_id, type }` + - `input_image_mask: optional object { file_id, image_url }` - The execution context that produced this tool call. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `Direct object { type }` + - `file_id: optional string` - - `type: "direct"` + File ID for the mask image. - The caller type. Always `direct`. + - `image_url: optional string` - - `"direct"` + Base64-encoded mask image. - - `Program object { caller_id, type }` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `caller_id: string` + The image generation model to use. Default: `gpt-image-1`. - The call ID of the program item that produced this tool call. + - `string` - - `type: "program"` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - The caller type. Always `program`. + The image generation model to use. Default: `gpt-image-1`. - - `"program"` + - `"gpt-image-1"` - - `max_output_length: optional number` + - `"gpt-image-1-mini"` - The maximum number of UTF-8 characters captured for this shell call's combined output. + - `"gpt-image-1.5"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `moderation: optional "auto" or "low"` - The status of the shell call output. + Moderation level for the generated image. Default: `auto`. - - `"in_progress"` + - `"auto"` - - `"completed"` + - `"low"` - - `"incomplete"` + - `output_compression: optional number` - - `ApplyPatchCall object { call_id, operation, status, 4 more }` + Compression level for the output image. Default: 100. - A tool call representing a request to create, delete, or update files using diff patches. + - `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 apply patch tool call generated by the model. + - `"png"` - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + - `"webp"` - The specific create, delete, or update instruction for the apply_patch tool call. + - `"jpeg"` - - `CreateFile object { diff, path, type }` + - `partial_images: optional number` - Instruction for creating a new file via the apply_patch tool. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `diff: string` + - `quality: optional "low" or "medium" or "high" or "auto"` - Unified diff content to apply when creating the file. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `path: string` + - `"low"` - Path of the file to create relative to the workspace root. + - `"medium"` - - `type: "create_file"` + - `"high"` - The operation type. Always `create_file`. + - `"auto"` - - `"create_file"` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `DeleteFile object { path, 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`. - Instruction for deleting an existing file via the apply_patch tool. + - `string` - - `path: string` + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - Path of the file to delete relative to the workspace root. + 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: "delete_file"` + - `"1024x1024"` - The operation type. Always `delete_file`. + - `"1024x1536"` - - `"delete_file"` + - `"1536x1024"` - - `UpdateFile object { diff, path, type }` + - `"auto"` - Instruction for updating an existing file via the apply_patch tool. + - `LocalShell object { type }` - - `diff: string` + A tool that allows the model to execute shell commands in a local environment. - Unified diff content to apply to the existing file. + - `type: "local_shell"` - - `path: string` + The type of the local shell tool. Always `local_shell`. - Path of the file to update relative to the workspace root. + - `"local_shell"` - - `type: "update_file"` + - `Shell object { type, allowed_callers, environment }` - The operation type. Always `update_file`. + A tool that allows the model to execute shell commands. - - `"update_file"` + - `type: "shell"` - - `status: "in_progress" or "completed"` + The type of the shell tool. Always `shell`. - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `"shell"` - - `"in_progress"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"completed"` + The tool invocation context(s). - - `type: "apply_patch_call"` + - `"direct"` - The type of the item. Always `apply_patch_call`. + - `"programmatic"` - - `"apply_patch_call"` + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - `id: optional string` + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `type: "container_auto"` - - `agent: optional object { agent_name }` + Automatically creates a container for this request - The agent that produced this item. + - `"container_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 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`. + - `skills: optional array of BetaSkillReference or BetaInlineSkill` - - `"program"` + An optional list of skills referenced by id or inline data. - - `ApplyPatchCallOutput object { call_id, status, type, 4 more }` + - `BetaSkillReference object { skill_id, type, version }` - The streamed output emitted by an apply patch tool call. + - `skill_id: string` - - `call_id: string` + The ID of the referenced skill. - The unique ID of the apply patch tool call generated by the model. + - `type: "skill_reference"` - - `status: "completed" or "failed"` + References a skill created with the /v1/skills endpoint. - The status of the apply patch tool call output. One of `completed` or `failed`. + - `"skill_reference"` - - `"completed"` + - `version: optional string` - - `"failed"` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `type: "apply_patch_call_output"` + - `BetaInlineSkill object { description, name, source, type }` - The type of the item. Always `apply_patch_call_output`. + - `description: string` - - `"apply_patch_call_output"` + The description of the skill. - - `id: optional string` + - `name: string` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + 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. - - `caller: optional object { type } or object { caller_id, type }` + - `media_type: "application/zip"` - The execution context that produced this tool call. + The media type of the inline skill payload. Must be `application/zip`. - - `Direct object { type }` + - `"application/zip"` - - `type: "direct"` + - `type: "base64"` - The caller type. Always `direct`. + The type of the inline skill source. Must be `base64`. - - `"direct"` + - `"base64"` - - `Program object { caller_id, type }` + - `type: "inline"` - - `caller_id: string` + Defines an inline skill for this request. - The call ID of the program item that produced this tool call. + - `"inline"` - - `type: "program"` + - `BetaLocalEnvironment object { type, skills }` - The caller type. Always `program`. + - `type: "local"` - - `"program"` + Use a local computer environment. - - `output: optional string` + - `"local"` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + - `skills: optional array of BetaLocalSkill` - - `McpListTools object { id, server_label, tools, 3 more }` + An optional list of skills. - A list of tools available on an MCP server. + - `description: string` - - `id: string` + The description of the skill. - The unique ID of the list. + - `name: string` - - `server_label: string` + The name of the skill. - The label of the MCP server. + - `path: string` - - `tools: array of object { input_schema, name, annotations, description }` + The path to the directory containing the skill. - The tools available on the server. + - `BetaContainerReference object { container_id, type }` - - `input_schema: unknown` + - `container_id: string` - The JSON schema describing the tool's input. + The ID of the referenced container. - - `name: string` + - `type: "container_reference"` - The name of the tool. + References a container created with the /v1/containers endpoint - - `annotations: optional unknown` + - `"container_reference"` - Additional annotations about the tool. + - `Custom object { name, type, allowed_callers, 3 more }` - - `description: optional string` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - The description of the tool. + - `name: string` - - `type: "mcp_list_tools"` + The name of the custom tool, used to identify it in tool calls. - The type of the item. Always `mcp_list_tools`. + - `type: "custom"` - - `"mcp_list_tools"` + 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"` - - `error: optional string` + - `"programmatic"` - Error message if the server could not list tools. + - `defer_loading: optional boolean` - - `McpApprovalRequest object { id, arguments, name, 3 more }` + Whether this tool should be deferred and discovered via tool search. - A request for human approval of a tool invocation. + - `description: optional string` - - `id: string` + Optional description of the custom tool, used to provide more context. - The unique ID of the approval request. + - `format: optional object { type } or object { definition, syntax, type }` - - `arguments: string` + The input format for the custom tool. Default is unconstrained text. - A JSON string of arguments for the tool. + - `Text object { type }` - - `name: string` + Unconstrained free-form text. - The name of the tool to run. + - `type: "text"` - - `server_label: string` + Unconstrained text format. Always `text`. - The label of the MCP server making the request. + - `"text"` - - `type: "mcp_approval_request"` + - `Grammar object { definition, syntax, type }` - The type of the item. Always `mcp_approval_request`. + A grammar defined by the user. - - `"mcp_approval_request"` + - `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"` - - `McpApprovalResponse object { approval_request_id, approve, type, 3 more }` + - `"regex"` - A response to an MCP approval request. + - `type: "grammar"` - - `approval_request_id: string` + Grammar format. Always `grammar`. - The ID of the approval request being answered. + - `"grammar"` - - `approve: boolean` + - `Namespace object { description, name, tools, type }` - Whether the request was approved. + Groups function/custom tools under a shared namespace. - - `type: "mcp_approval_response"` + - `description: string` - The type of the item. Always `mcp_approval_response`. + A description of the namespace shown to the model. - - `"mcp_approval_response"` + - `name: string` - - `id: optional string` + The namespace name used in tool calls (for example, `crm`). - The unique ID of the approval response + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - - `agent: optional object { agent_name }` + The function/custom tools available inside this namespace. - The agent that produced this item. + - `Function object { name, type, allowed_callers, 5 more }` - - `agent_name: string` + - `name: string` - The canonical name of the agent that produced this item. + - `type: "function"` - - `reason: optional string` + - `"function"` - Optional reason for the decision. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `McpCall object { id, arguments, name, 7 more }` + The tool invocation context(s). - An invocation of a tool on an MCP server. + - `"direct"` - - `id: string` + - `"programmatic"` - The unique ID of the tool call. + - `defer_loading: optional boolean` - - `arguments: string` + Whether this function should be deferred and discovered via tool search. - A JSON string of the arguments passed to the tool. + - `description: optional string` - - `name: string` + - `output_schema: optional map[unknown]` - The name of the tool that was run. + 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 running the tool. + - `strict: optional boolean` - - `type: "mcp_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. - The type of the item. Always `mcp_call`. + - `Custom object { name, type, allowed_callers, 3 more }` - - `"mcp_call"` + 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`. - - `approval_request_id: optional string` + - `"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. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `error: optional string` + The tool invocation context(s). - The error from the tool call, if any. + - `"direct"` - - `output: optional string` + - `"programmatic"` - The output from the tool call. + - `defer_loading: optional boolean` - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + Whether this tool should be deferred and discovered via tool search. - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `description: optional string` - - `"in_progress"` + Optional description of the custom tool, used to provide more context. - - `"completed"` + - `format: optional object { type } or object { definition, syntax, type }` - - `"incomplete"` + The input format for the custom tool. Default is unconstrained text. - - `"calling"` + - `Text object { type }` - - `"failed"` + Unconstrained free-form text. - - `CustomToolCallOutput object { call_id, output, type, 3 more }` + - `type: "text"` - The output of a custom tool call from your code, being sent back to the model. + Unconstrained text format. Always `text`. - - `call_id: string` + - `"text"` - The call ID, used to map this custom tool call output to a custom tool call. + - `Grammar object { definition, syntax, type }` - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + A grammar defined by the user. - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `definition: string` - - `StringOutput = string` + The grammar definition. - A string of the output of the custom tool call. + - `syntax: "lark" or "regex"` - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + The syntax of the grammar definition. One of `lark` or `regex`. - Text, image, or file output of the custom tool call. + - `"lark"` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `"regex"` - A text input to the model. + - `type: "grammar"` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + Grammar format. Always `grammar`. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `"grammar"` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `type: "namespace"` - A file input to the model. + The type of the tool. Always `namespace`. - - `type: "custom_tool_call_output"` + - `"namespace"` - The type of the custom tool call output. Always `custom_tool_call_output`. + - `ToolSearch object { type, description, execution, parameters }` - - `"custom_tool_call_output"` + Hosted or BYOT tool search configuration for deferred tools. - - `id: optional string` + - `type: "tool_search"` - The unique ID of the custom tool call output in the OpenAI platform. + 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"` - - `caller: optional object { type } or object { caller_id, type }` + Whether tool search is executed by the server or by the client. - The execution context that produced this tool call. + - `"server"` - - `Direct object { type }` + - `"client"` - - `type: "direct"` + - `parameters: optional unknown` - The caller type. Always `direct`. + Parameter schema for a client-executed tool search tool. - - `"direct"` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - - `Program object { caller_id, 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). - - `caller_id: string` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - The call ID of the program item that produced this tool call. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `type: "program"` + - `"web_search_preview"` - The caller type. Always `program`. + - `"web_search_preview_2025_03_11"` - - `"program"` + - `search_content_types: optional array of "text" or "image"` - - `CustomToolCall object { call_id, input, name, 5 more }` + - `"text"` - A call to a custom tool created by the model. + - `"image"` - - `call_id: string` + - `search_context_size: optional "low" or "medium" or "high"` - An identifier used to map this custom tool call to a 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. - - `input: string` + - `"low"` - The input for the custom tool call generated by the model. + - `"medium"` - - `name: string` + - `"high"` - The name of the custom tool being called. + - `user_location: optional object { type, city, country, 2 more }` - - `type: "custom_tool_call"` + The user's location. - The type of the custom tool call. Always `custom_tool_call`. + - `type: "approximate"` - - `"custom_tool_call"` + The type of location approximation. Always `approximate`. - - `id: optional string` + - `"approximate"` - The unique ID of the custom tool call in the OpenAI platform. + - `city: optional string` - - `agent: optional object { agent_name }` + Free text input for the city of the user, e.g. `San Francisco`. - The agent that produced this item. + - `country: optional string` - - `agent_name: string` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The canonical name of the agent that produced this item. + - `region: optional string` - - `caller: optional object { type } or object { caller_id, type }` + Free text input for the region of the user, e.g. `California`. - The execution context that produced this tool call. + - `timezone: optional string` - - `Direct object { type }` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `type: "direct"` + - `ApplyPatch object { type, allowed_callers }` - - `"direct"` + Allows the assistant to create, delete, or update files using unified diffs. - - `Program object { caller_id, type }` + - `type: "apply_patch"` - - `caller_id: string` + The type of the tool. Always `apply_patch`. - The call ID of the program item that produced this tool call. + - `"apply_patch"` - - `type: "program"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"program"` + The tool invocation context(s). - - `namespace: optional string` + - `"direct"` - The namespace of the custom tool being called. + - `"programmatic"` - - `CompactionTrigger object { type, agent }` + - `type: "tool_search_output"` - Compacts the current context. Must be the final input item. + The item type. Always `tool_search_output`. - - `type: "compaction_trigger"` + - `"tool_search_output"` - The type of the item. Always `compaction_trigger`. + - `id: optional string` - - `"compaction_trigger"` + The unique ID of this tool search output. - `agent: optional object { agent_name }` @@ -104805,1028 +103386,1038 @@ 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. + - `call_id: optional string` - - `agent: optional object { agent_name }` + The unique ID of the tool search call generated by the model. - The agent that produced this item. + - `execution: optional "server" or "client"` - - `agent_name: string` + Whether tool search was executed by the server or by the client. - The canonical name of the agent that produced this item. + - `"server"` - - `type: optional "item_reference"` + - `"client"` - The type of item to reference. Always `item_reference`. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"item_reference"` + The status of the tool search output. - - `Program object { id, call_id, code, 3 more }` + - `"in_progress"` - - `id: string` + - `"completed"` - The unique ID of this program item. + - `"incomplete"` - - `call_id: string` + - `AdditionalTools object { role, tools, type, 2 more }` - The stable call ID of the program item. + - `role: "developer"` - - `code: string` + The role that provided the additional tools. Only `developer` is supported. - The JavaScript source executed by programmatic tool calling. + - `"developer"` - - `fingerprint: 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` - Opaque program replay fingerprint that must be round-tripped. + A list of additional tools made available at this item. - - `type: "program"` + - `Function object { name, parameters, strict, 5 more }` - The item type. Always `program`. + 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). - - `"program"` + - `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` - - `ProgramOutput object { id, call_id, result, 3 more }` + Whether strict parameter validation is enforced for this function tool. - - `id: string` + - `type: "function"` - The unique ID of this program output item. + The type of the function tool. Always `function`. - - `call_id: string` + - `"function"` - 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 function is deferred and loaded via tool search. - - `"incomplete"` + - `description: optional string` - - `type: "program_output"` + A description of the function. Used by the model to determine whether or not to call the function. - The item type. Always `program_output`. + - `output_schema: optional map[unknown]` - - `"program_output"` + 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`. - - `metadata: map[string]` + - `"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. + - `vector_store_ids: array of string` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The IDs of the vector stores to search. - - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` + - `filters: optional object { key, type, value } or object { filters, 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](https://platform.openai.com/docs/models) - to browse and compare available models. + A filter to apply. - - `"gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more` + - `ComparisonFilter object { key, type, value }` - 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](https://platform.openai.com/docs/models) - to browse and compare available models. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `"gpt-5.6-sol"` + - `key: string` - - `"gpt-5.6-terra"` + The key to compare against the value. - - `"gpt-5.6-luna"` + - `type: "eq" or "ne" or "gt" or 5 more` - - `"gpt-5.4"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `"gpt-5.4-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-5.4-nano"` + - `"eq"` - - `"gpt-5.4-mini-2026-03-17"` + - `"ne"` - - `"gpt-5.4-nano-2026-03-17"` + - `"gt"` - - `"gpt-5.3-chat-latest"` + - `"gte"` - - `"gpt-5.2"` + - `"lt"` - - `"gpt-5.2-2025-12-11"` + - `"lte"` - - `"gpt-5.2-chat-latest"` + - `"in"` - - `"gpt-5.2-pro"` + - `"nin"` - - `"gpt-5.2-pro-2025-12-11"` + - `value: string or number or boolean or array of string or number` - - `"gpt-5.1"` + The value to compare against the attribute key; supports string, number, or boolean types. - - `"gpt-5.1-2025-11-13"` + - `string` - - `"gpt-5.1-codex"` + - `number` - - `"gpt-5.1-mini"` + - `boolean` - - `"gpt-5.1-chat-latest"` + - `array of string or number` - - `"gpt-5"` + - `string` - - `"gpt-5-mini"` + - `number` - - `"gpt-5-nano"` + - `CompoundFilter object { filters, type }` - - `"gpt-5-2025-08-07"` + Combine multiple filters using `and` or `or`. - - `"gpt-5-mini-2025-08-07"` + - `filters: array of object { key, type, value } or unknown` - - `"gpt-5-nano-2025-08-07"` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `"gpt-5-chat-latest"` + - `ComparisonFilter object { key, type, value }` - - `"gpt-4.1"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `"gpt-4.1-mini"` + - `key: string` - - `"gpt-4.1-nano"` + The key to compare against the value. - - `"gpt-4.1-2025-04-14"` + - `type: "eq" or "ne" or "gt" or 5 more` - - `"gpt-4.1-mini-2025-04-14"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `"gpt-4.1-nano-2025-04-14"` + - `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 - - `"o4-mini"` + - `"eq"` - - `"o4-mini-2025-04-16"` + - `"ne"` - - `"o3"` + - `"gt"` - - `"o3-2025-04-16"` + - `"gte"` - - `"o3-mini"` + - `"lt"` - - `"o3-mini-2025-01-31"` + - `"lte"` - - `"o1"` + - `"in"` - - `"o1-2024-12-17"` + - `"nin"` - - `"o1-preview"` + - `value: string or number or boolean or array of string or number` - - `"o1-preview-2024-09-12"` + The value to compare against the attribute key; supports string, number, or boolean types. - - `"o1-mini"` + - `string` - - `"o1-mini-2024-09-12"` + - `number` - - `"gpt-4o"` + - `boolean` - - `"gpt-4o-2024-11-20"` + - `array of string or number` - - `"gpt-4o-2024-08-06"` + - `string` - - `"gpt-4o-2024-05-13"` + - `number` - - `"gpt-4o-audio-preview"` + - `unknown` - - `"gpt-4o-audio-preview-2024-10-01"` + - `type: "and" or "or"` - - `"gpt-4o-audio-preview-2024-12-17"` + Type of operation: `and` or `or`. - - `"gpt-4o-audio-preview-2025-06-03"` + - `"and"` - - `"gpt-4o-mini-audio-preview"` + - `"or"` - - `"gpt-4o-mini-audio-preview-2024-12-17"` + - `max_num_results: optional number` - - `"gpt-4o-search-preview"` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `"gpt-4o-mini-search-preview"` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `"gpt-4o-search-preview-2025-03-11"` + Ranking options for search. - - `"gpt-4o-mini-search-preview-2025-03-11"` + - `hybrid_search: optional object { embedding_weight, text_weight }` - - `"chatgpt-4o-latest"` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `"codex-mini-latest"` + - `embedding_weight: number` - - `"gpt-4o-mini"` + The weight of the embedding in the reciprocal ranking fusion. - - `"gpt-4o-mini-2024-07-18"` + - `text_weight: number` - - `"gpt-4-turbo"` + The weight of the text in the reciprocal ranking fusion. - - `"gpt-4-turbo-2024-04-09"` + - `ranker: optional "auto" or "default-2024-11-15"` - - `"gpt-4-0125-preview"` + The ranker to use for the file search. - - `"gpt-4-turbo-preview"` + - `"auto"` - - `"gpt-4-1106-preview"` + - `"default-2024-11-15"` - - `"gpt-4-vision-preview"` + - `score_threshold: optional number` - - `"gpt-4"` + 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-0314"` + - `Computer object { type }` - - `"gpt-4-0613"` + 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"` + - `type: "computer"` - - `"gpt-4-32k-0314"` + The type of the computer tool. Always `computer`. - - `"gpt-4-32k-0613"` + - `"computer"` - - `"gpt-3.5-turbo"` + - `ComputerUsePreview object { display_height, display_width, environment, type }` - - `"gpt-3.5-turbo-16k"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"gpt-3.5-turbo-0301"` + - `display_height: number` - - `"gpt-3.5-turbo-0613"` + The height of the computer display. - - `"gpt-3.5-turbo-1106"` + - `display_width: number` - - `"gpt-3.5-turbo-0125"` + The width of the computer display. - - `"gpt-3.5-turbo-16k-0613"` + - `environment: "windows" or "mac" or "linux" or 2 more` - - `"o1-pro"` + The type of computer environment to control. - - `"o1-pro-2025-03-19"` + - `"windows"` - - `"o3-pro"` + - `"mac"` - - `"o3-pro-2025-06-10"` + - `"linux"` - - `"o3-deep-research"` + - `"ubuntu"` - - `"o3-deep-research-2025-06-26"` + - `"browser"` - - `"o4-mini-deep-research"` + - `type: "computer_use_preview"` - - `"o4-mini-deep-research-2025-06-26"` + The type of the computer use tool. Always `computer_use_preview`. - - `"computer-use-preview"` + - `"computer_use_preview"` - - `"computer-use-preview-2025-03-11"` + - `WebSearch object { type, filters, search_context_size, user_location }` - - `"gpt-5-codex"` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - - `"gpt-5-pro"` + - `type: "web_search" or "web_search_2025_08_26"` - - `"gpt-5-pro-2025-10-06"` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `"gpt-5.1-codex-max"` + - `"web_search"` - - `string` + - `"web_search_2025_08_26"` - - `object: "response"` + - `filters: optional object { allowed_domains }` - The object type of this resource - always set to `response`. + Filters for the search. - - `"response"` + - `allowed_domains: optional array of string` - - `output: array of BetaResponseOutputItem` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - An array of content items generated by the model. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - 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. + - `search_context_size: optional "low" or "medium" or "high"` - - `BetaResponseOutputMessage object { id, content, role, 4 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. - An output message from the model. + - `"low"` - - `FileSearchCall object { id, queries, status, 3 more }` + - `"medium"` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `"high"` - - `id: string` + - `user_location: optional object { city, country, region, 2 more }` - The unique ID of the file search tool call. + The approximate location of the user. - - `queries: array of string` + - `city: optional string` - The queries used to search for files. + Free text input for the city of the user, e.g. `San Francisco`. - - `status: "in_progress" or "searching" or "completed" or 2 more` + - `country: optional string` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + 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` - - `"searching"` + 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`. - - `"failed"` + - `type: optional "approximate"` - - `type: "file_search_call"` + The type of location approximation. Always `approximate`. - The type of the file search tool call. Always `file_search_call`. + - `"approximate"` - - `"file_search_call"` + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `agent: optional object { agent_name }` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - The agent that produced this item. + - `server_label: string` - - `agent_name: string` + A label for this MCP server, used to identify it in tool calls. - The canonical name of the agent that produced this item. + - `type: "mcp"` - - `results: optional array of object { attributes, file_id, filename, 2 more }` + The type of the MCP tool. Always `mcp`. - The results of the file search tool call. + - `"mcp"` - - `attributes: optional map[string or number or boolean]` + - `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. Keys are strings - with a maximum length of 64 characters. Values are strings with a maximum - length of 512 characters, booleans, or numbers. + The tool invocation context(s). - - `string` + - `"direct"` - - `number` + - `"programmatic"` - - `boolean` + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `file_id: optional string` + List of allowed tool names or a filter object. - The unique ID of the file. + - `McpAllowedTools = array of string` - - `filename: optional string` + A string array of allowed tool names - The name of the file. + - `McpToolFilter object { read_only, tool_names }` - - `score: optional number` + A filter object to specify which tools are allowed. - The relevance score of the file - a value between 0 and 1. + - `read_only: optional boolean` - - `text: 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 text that was retrieved from the file. + - `tool_names: optional array of string` - - `FunctionCall object { arguments, call_id, name, 6 more }` + List of allowed tool names. - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `authorization: optional string` - - `arguments: string` + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - A JSON string of the arguments to pass to the function. + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `call_id: string` + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). - The unique ID of the function tool call generated by the model. + Currently supported `connector_id` values are: - - `name: string` + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - The name of the function to run. + - `"connector_dropbox"` - - `type: "function_call"` + - `"connector_gmail"` - The type of the function tool call. Always `function_call`. + - `"connector_googlecalendar"` - - `"function_call"` + - `"connector_googledrive"` - - `id: optional string` + - `"connector_microsoftteams"` - The unique ID of the function tool call. + - `"connector_outlookcalendar"` - - `agent: optional object { agent_name }` + - `"connector_outlookemail"` - The agent that produced this item. + - `"connector_sharepoint"` - - `agent_name: string` + - `defer_loading: optional boolean` - The canonical name of the agent that produced this item. + Whether this MCP tool is deferred and discovered via tool search. - - `caller: optional object { type } or object { caller_id, type }` + - `headers: optional map[string]` - The execution context that produced this tool call. + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `Direct object { type }` + - `require_approval: optional object { always, never } or "always" or "never"` - - `type: "direct"` + Specify which of the MCP server's tools require approval. - - `"direct"` + - `McpToolApprovalFilter object { always, never }` - - `Program object { caller_id, 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. - - `caller_id: string` + - `always: optional object { read_only, tool_names }` - The call ID of the program item that produced this tool call. + A filter object to specify which tools are allowed. - - `type: "program"` + - `read_only: optional boolean` - - `"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. - - `namespace: optional string` + - `tool_names: optional array of string` - The namespace of the function to run. + List of allowed tool names. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `never: optional object { read_only, tool_names }` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when 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` - - `FunctionCallOutput object { id, call_id, output, 5 more }` + List of allowed tool names. - - `id: string` + - `McpToolApprovalSetting = "always" or "never"` - The unique ID of the function call tool 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. - - `call_id: string` + - `"always"` - The unique ID of the function tool call generated by the model. + - `"never"` - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `server_description: optional string` - The output from the function call generated by your code. - Can be a string or an list of output content. + Optional description of the MCP server, used to provide more context. - - `StringOutput = string` + - `server_url: optional string` - A string of the output of the function call. + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `tunnel_id: optional string` - Text, image, or file output of the function 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. - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `CodeInterpreter object { container, type, allowed_callers }` - A text input to the model. + A tool that runs Python code to help generate a response to a prompt. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + 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. - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `string` - A file input to the model. + The container ID. - - `status: "in_progress" or "completed" or "incomplete"` + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `"in_progress"` + - `type: "auto"` - - `"completed"` + Always `auto`. - - `"incomplete"` + - `"auto"` - - `type: "function_call_output"` + - `file_ids: optional array of string` - The type of the function tool call output. Always `function_call_output`. + An optional list of uploaded files to make available to your code. - - `"function_call_output"` + - `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"` - - `caller: optional object { type } or object { caller_id, type }` + - `"64g"` - The execution context that produced this tool call. + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `Direct object { type }` + Network access policy for the container. - - `type: "direct"` + - `BetaContainerNetworkPolicyDisabled object { type }` - The caller type. Always `direct`. + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `"direct"` + - `type: "code_interpreter"` - - `Program object { caller_id, type }` + The type of the code interpreter tool. Always `code_interpreter`. - - `caller_id: string` + - `"code_interpreter"` - 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). - The caller type. Always `program`. + - `"direct"` - - `"program"` + - `"programmatic"` - - `created_by: optional string` + - `ProgrammaticToolCalling object { type }` - The identifier of the actor that created the item. + - `type: "programmatic_tool_calling"` - - `AgentMessage object { id, author, content, 3 more }` + The type of the tool. Always `programmatic_tool_calling`. - - `id: string` + - `"programmatic_tool_calling"` - The unique ID of the agent message. + - `ImageGeneration object { type, action, background, 9 more }` - - `author: string` + A tool that generates images using the GPT image models. - The sending agent identity. + - `type: "image_generation"` - - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` + The type of the image generation tool. Always `image_generation`. - Encrypted content sent between agents. + - `"image_generation"` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `action: optional "generate" or "edit" or "auto"` - A text input to the model. + Whether to generate a new image or edit an existing image. Default: `auto`. - - `BetaResponseOutputText object { annotations, text, type, logprobs }` + - `"generate"` - A text output from the model. + - `"edit"` - - `Text object { text, type }` + - `"auto"` - A text content. + - `background: optional "transparent" or "opaque" or "auto"` - - `text: string` + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - - `type: "text"` + - `"transparent"` - - `"text"` + - `"opaque"` - - `SummaryText object { text, type }` + - `"auto"` - A summary text from the model. + - `input_fidelity: optional "high" or "low"` - - `text: 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`. - A summary of the reasoning output from the model so far. + - `"high"` - - `type: "summary_text"` + - `"low"` - The type of the object. Always `summary_text`. + - `input_image_mask: optional object { file_id, image_url }` - - `"summary_text"` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `ReasoningText object { text, type }` + - `file_id: optional string` - Reasoning text from the model. + File ID for the mask image. - - `text: string` + - `image_url: optional string` - The reasoning text from the model. + Base64-encoded mask image. - - `type: "reasoning_text"` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - The type of the reasoning text. Always `reasoning_text`. + The image generation model to use. Default: `gpt-image-1`. - - `"reasoning_text"` + - `string` - - `BetaResponseOutputRefusal object { refusal, type }` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - A refusal from the model. + The image generation model to use. Default: `gpt-image-1`. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `"gpt-image-1"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `"gpt-image-1-mini"` - - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` + - `"gpt-image-1.5"` - A screenshot of a computer. + - `moderation: optional "auto" or "low"` - - `detail: "low" or "high" or "auto" or "original"` + Moderation level for the generated image. Default: `auto`. - The detail level of the screenshot 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: string` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - The identifier of an uploaded file that contains the screenshot. + - `"png"` - - `image_url: string` + - `"webp"` - The URL of the screenshot image. + - `"jpeg"` - - `type: "computer_screenshot"` + - `partial_images: optional number` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `"computer_screenshot"` + - `quality: optional "low" or "medium" or "high" or "auto"` - - `prompt_cache_breakpoint: optional object { mode }` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `"low"` - - `mode: "explicit"` + - `"medium"` - The breakpoint mode. Always `explicit`. + - `"high"` - - `"explicit"` + - `"auto"` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - A file input to 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`. - - `EncryptedContent object { encrypted_content, type }` + - `string` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `encrypted_content: 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`. - Opaque encrypted content. + - `"1024x1024"` - - `type: "encrypted_content"` + - `"1024x1536"` - The type of the input item. Always `encrypted_content`. + - `"1536x1024"` - - `"encrypted_content"` + - `"auto"` - - `recipient: string` + - `LocalShell object { type }` - The destination agent identity. + A tool that allows the model to execute shell commands in a local environment. - - `type: "agent_message"` + - `type: "local_shell"` - The type of the item. Always `agent_message`. + The type of the local shell tool. Always `local_shell`. - - `"agent_message"` + - `"local_shell"` - - `agent: optional object { agent_name }` + - `Shell object { type, allowed_callers, environment }` - The agent that produced this item. + A tool that allows the model to execute shell commands. - - `agent_name: string` + - `type: "shell"` - The canonical name of the agent that produced this item. + The type of the shell tool. Always `shell`. - - `MultiAgentCall object { id, action, arguments, 3 more }` + - `"shell"` - - `id: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The unique ID of the multi-agent call item. + The tool invocation context(s). - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `"direct"` - The multi-agent action to execute. + - `"programmatic"` - - `"spawn_agent"` + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - `"interrupt_agent"` + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - - `"list_agents"` + - `BetaLocalEnvironment object { type, skills }` - - `"send_message"` + - `BetaContainerReference object { container_id, type }` - - `"followup_task"` + - `Custom object { name, type, allowed_callers, 3 more }` - - `"wait_agent"` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `arguments: string` + - `name: string` - The JSON string of arguments generated for the action. + The name of the custom tool, used to identify it in tool calls. - - `call_id: string` + - `type: "custom"` - The unique ID linking this call to its output. + The type of the custom tool. Always `custom`. - - `type: "multi_agent_call"` + - `"custom"` - The type of the multi-agent call. Always `multi_agent_call`. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"multi_agent_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 tool should be deferred and discovered via tool search. - - `MultiAgentCallOutput object { id, action, call_id, 3 more }` + - `description: optional string` - - `id: string` + Optional description of the custom tool, used to provide more context. - The unique ID of the multi-agent call output item. + - `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 produced this result. + - `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. - - `call_id: string` + - `definition: string` - The unique ID of the multi-agent call. + The grammar definition. - - `output: array of BetaResponseOutputText` + - `syntax: "lark" or "regex"` - Text output returned by the multi-agent action. + The syntax of the grammar definition. One of `lark` or `regex`. - - `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 }` + - `"lark"` - The annotations of the text output. + - `"regex"` - - `text: string` + - `type: "grammar"` - The text output from the model. + Grammar format. Always `grammar`. - - `type: "output_text"` + - `"grammar"` - The type of the output text. Always `output_text`. + - `Namespace object { description, name, tools, type }` - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + Groups function/custom tools under a shared namespace. - - `type: "multi_agent_call_output"` + - `description: string` - The type of the multi-agent result. Always `multi_agent_call_output`. + A description of the namespace shown to the model. - - `"multi_agent_call_output"` + - `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 }` - - `WebSearchCall object { id, action, status, 2 more }` + - `name: string` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `type: "function"` - - `id: string` + - `"function"` - 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. + - `defer_loading: optional boolean` - - `type: "search"` + Whether this function should be deferred and discovered via tool search. - The action type. + - `description: optional string` - - `"search"` + - `output_schema: optional map[unknown]` - - `queries: 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 search queries. + - `parameters: optional unknown` - - `query: optional string` + - `strict: optional boolean` - The search query. + 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. - - `sources: optional array of object { type, url }` + - `Custom object { name, type, allowed_callers, 3 more }` - The sources used in the search. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `type: "url"` + - `name: string` - The type of source. Always `url`. + The name of the custom tool, used to identify it in tool calls. - - `"url"` + - `type: "custom"` - - `url: string` + The type of the custom tool. Always `custom`. - The URL of the source. + - `"custom"` - - `OpenPage object { type, url }` + - `allowed_callers: optional array of "direct" or "programmatic"` - Action type "open_page" - Opens a specific URL from search results. + The tool invocation context(s). - - `type: "open_page"` + - `"direct"` - The action type. + - `"programmatic"` - - `"open_page"` + - `defer_loading: optional boolean` - - `url: optional string` + Whether this tool should be deferred and discovered via tool search. - The URL opened by the model. + - `description: optional string` - - `FindInPage object { pattern, type, url }` + Optional description of the custom tool, used to provide more context. - Action type "find_in_page": Searches for a pattern within a loaded page. + - `format: optional object { type } or object { definition, syntax, type }` - - `pattern: string` + The input format for the custom tool. Default is unconstrained text. - The pattern or text to search for within the page. + - `Text object { type }` - - `type: "find_in_page"` + Unconstrained free-form text. - The action type. + - `type: "text"` - - `"find_in_page"` + Unconstrained text format. Always `text`. - - `url: string` + - `"text"` - The URL of the page searched for the pattern. + - `Grammar object { definition, syntax, type }` - - `status: "in_progress" or "searching" or "completed" or "failed"` + A grammar defined by the user. - The status of the web search tool call. + - `definition: string` - - `"in_progress"` + The grammar definition. - - `"searching"` + - `syntax: "lark" or "regex"` - - `"completed"` + The syntax of the grammar definition. One of `lark` or `regex`. - - `"failed"` + - `"lark"` - - `type: "web_search_call"` + - `"regex"` - The type of the web search tool call. Always `web_search_call`. + - `type: "grammar"` - - `"web_search_call"` + 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"` - - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` + - `ToolSearch object { type, description, execution, parameters }` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + Hosted or BYOT tool search configuration for deferred tools. - - `id: string` + - `type: "tool_search"` - The unique ID of the computer call. + The type of the tool. Always `tool_search`. - - `call_id: string` + - `"tool_search"` - An identifier used when responding to the tool call with output. + - `description: optional string` - - `pending_safety_checks: array of object { id, code, message }` + Description shown to the model for a client-executed tool search tool. - The pending safety checks for the computer call. + - `execution: optional "server" or "client"` - - `id: string` + Whether tool search is executed by the server or by the client. - The ID of the pending safety check. + - `"server"` - - `code: optional string` + - `"client"` - The type of the pending safety check. + - `parameters: optional unknown` - - `message: optional string` + Parameter schema for a client-executed tool search tool. - Details about the pending safety check. + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - - `status: "in_progress" or "completed" or "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). - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `"in_progress"` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `"completed"` + - `"web_search_preview"` - - `"incomplete"` + - `"web_search_preview_2025_03_11"` - - `type: "computer_call"` + - `search_content_types: optional array of "text" or "image"` - The type of the computer call. Always `computer_call`. + - `"text"` - - `"computer_call"` + - `"image"` - - `action: optional BetaComputerAction` + - `search_context_size: optional "low" or "medium" or "high"` - A click action. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `actions: optional BetaComputerActionList` + - `"low"` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `"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 { id, call_id, output, 5 more }` + The type of location approximation. Always `approximate`. - - `id: string` + - `"approximate"` - The unique ID of the computer call tool output. + - `city: optional string` - - `call_id: string` + Free text input for the city of the user, e.g. `San Francisco`. - The ID of the computer tool call that produced the output. + - `country: optional string` - - `output: BetaResponseComputerToolCallOutputScreenshot` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - A computer screenshot image used with the computer use tool. + - `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 }` @@ -105836,16 +104427,12 @@ 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](https://platform.openai.com/docs/guides/conversation-state). + [managing context](/docs/guides/conversation-state). - `id: string` @@ -105909,29 +104496,23 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"incomplete"` - - `Program object { id, call_id, code, 3 more }` - - - `id: string` - - The unique ID of the program item. - - - `call_id: string` + - `Compaction object { encrypted_content, type, id, agent }` - The stable call ID of the program item. + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). - - `code: string` + - `encrypted_content: string` - The JavaScript source executed by programmatic tool calling. + The encrypted content of the compaction summary. - - `fingerprint: string` + - `type: "compaction"` - Opaque program replay fingerprint that must be round-tripped. + The type of the item. Always `compaction`. - - `type: "program"` + - `"compaction"` - The type of the item. Always `program`. + - `id: optional string` - - `"program"` + The ID of the compaction item. - `agent: optional object { agent_name }` @@ -105941,79 +104522,35 @@ 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` - - 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. + - `ImageGenerationCall object { id, result, status, 2 more }` - - `ToolSearchCall object { id, arguments, call_id, 5 more }` + An image generation request made by the model. - `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. + 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 }` @@ -106023,1053 +104560,958 @@ 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. - - - `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. + The unique ID of the code interpreter tool call. - - `type: "function"` + - `code: string` - The type of the function tool. Always `function`. + The code to run, or null if not available. - - `"function"` + - `container_id: string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The ID of the container used to run the code. - The tool invocation context(s). + - `outputs: array of object { logs, type } or object { type, url }` - - `"direct"` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `"programmatic"` + - `Logs object { logs, type }` - - `defer_loading: optional boolean` + The logs output from the code interpreter. - Whether this function is deferred and loaded via tool search. + - `logs: string` - - `description: optional string` + The logs output from the code interpreter. - 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]` + The type of the output. 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 }` + - `Image object { type, url }` - 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 image output from the code interpreter. - - `type: "file_search"` + - `type: "image"` - The type of the file search tool. Always `file_search`. + The type of the output. Always `image`. - - `"file_search"` + - `"image"` - - `vector_store_ids: array of string` + - `url: string` - The IDs of the vector stores to search. + The URL of the image output from the code interpreter. - - `filters: optional object { key, type, value } or object { filters, type }` + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - A filter to apply. + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `ComparisonFilter object { key, type, value }` + - `"in_progress"` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `"completed"` - - `key: string` + - `"incomplete"` - The key to compare against the value. + - `"interpreting"` - - `type: "eq" or "ne" or "gt" or 5 more` + - `"failed"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `type: "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 + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `"eq"` + - `"code_interpreter_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"` + - `LocalShellCall object { id, action, call_id, 3 more }` - - `"in"` + A tool call to run a command on the local shell. - - `"nin"` + - `id: string` - - `value: string or number or boolean or array of string or number` + The unique ID of the local shell call. - The value to compare against the attribute key; supports string, number, or boolean types. + - `action: object { command, env, type, 3 more }` - - `string` + Execute a shell command on the server. - - `number` + - `command: array of string` - - `boolean` + The command to run. - - `array of string or number` + - `env: map[string]` - - `string` + Environment variables to set for the command. - - `number` + - `type: "exec"` - - `CompoundFilter object { filters, type }` + The type of the local shell action. Always `exec`. - Combine multiple filters using `and` or `or`. + - `"exec"` - - `filters: array of object { key, type, value } or unknown` + - `timeout_ms: optional number` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + Optional timeout in milliseconds for the command. - - `ComparisonFilter object { key, type, value }` + - `user: optional string` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + Optional user to run the command as. - - `key: string` + - `working_directory: optional string` - The key to compare against the value. + Optional working directory to run the command in. - - `type: "eq" or "ne" or "gt" or 5 more` + - `call_id: string` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The unique ID of the local shell tool call generated by the model. - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `status: "in_progress" or "completed" or "incomplete"` - - `"eq"` + The status of the local shell call. - - `"ne"` + - `"in_progress"` - - `"gt"` + - `"completed"` - - `"gte"` + - `"incomplete"` - - `"lt"` + - `type: "local_shell_call"` - - `"lte"` + The type of the local shell call. Always `local_shell_call`. - - `"in"` + - `"local_shell_call"` - - `"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` + - `LocalShellCallOutput object { id, output, type, 2 more }` - - `boolean` + The output of a local shell tool call. - - `array of string or number` + - `id: string` - - `string` + The unique ID of the local shell tool call generated by the model. - - `number` + - `output: string` - - `unknown` + A JSON string of the output of the local shell tool call. - - `type: "and" or "or"` + - `type: "local_shell_call_output"` - Type of operation: `and` or `or`. + The type of the local shell tool call output. Always `local_shell_call_output`. - - `"and"` + - `"local_shell_call_output"` - - `"or"` + - `agent: optional object { agent_name }` - - `max_num_results: optional number` + The agent that produced this item. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `agent_name: string` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + The canonical name of the agent that produced this item. - Ranking options for search. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `hybrid_search: optional object { embedding_weight, text_weight }` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - 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` + - `ShellCall object { action, call_id, type, 5 more }` - The weight of the text in the reciprocal ranking fusion. + A tool representing a request to execute one or more shell commands. - - `ranker: optional "auto" or "default-2024-11-15"` + - `action: object { commands, max_output_length, timeout_ms }` - The ranker to use for the file search. + The shell commands and limits that describe how to run the tool call. - - `"auto"` + - `commands: array of string` - - `"default-2024-11-15"` + Ordered shell commands for the execution environment to run. - - `score_threshold: optional number` + - `max_output_length: 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 UTF-8 characters to capture from combined stdout and stderr output. - - `Computer object { type }` + - `timeout_ms: optional number` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + Maximum wall-clock time in milliseconds to allow the shell commands to run. - - `type: "computer"` + - `call_id: string` - The type of the computer tool. Always `computer`. + The unique ID of the shell tool call generated by the model. - - `"computer"` + - `type: "shell_call"` - - `ComputerUsePreview object { display_height, display_width, environment, type }` + The type of the item. Always `shell_call`. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `"shell_call"` - - `display_height: number` + - `id: optional string` - The height of the computer display. + The unique ID of the shell tool call. Populated when this item is returned via API. - - `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"` + - `caller: optional object { type } or object { caller_id, type }` - - `"mac"` + The execution context that produced this tool call. - - `"linux"` + - `Direct object { type }` - - `"ubuntu"` + - `type: "direct"` - - `"browser"` + The caller type. Always `direct`. - - `type: "computer_use_preview"` + - `"direct"` - The type of the computer use tool. Always `computer_use_preview`. + - `Program object { caller_id, type }` - - `"computer_use_preview"` + - `caller_id: string` - - `WebSearch object { type, filters, search_context_size, user_location }` + The call ID of the program item that produced this tool call. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `type: "program"` - - `type: "web_search" or "web_search_2025_08_26"` + The caller type. Always `program`. - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `"program"` - - `"web_search"` + - `environment: optional BetaLocalEnvironment or BetaContainerReference` - - `"web_search_2025_08_26"` + The environment to execute the shell commands in. - - `filters: optional object { allowed_domains }` + - `BetaLocalEnvironment object { type, skills }` - Filters for the search. + - `BetaContainerReference object { container_id, type }` - - `allowed_domains: optional array of string` + - `status: optional "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 shell call. One of `in_progress`, `completed`, or `incomplete`. - 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"` + - `ShellCallOutput object { call_id, output, type, 5 more }` - - `"medium"` + The streamed output items emitted by a shell tool call. - - `"high"` + - `call_id: string` - - `user_location: optional object { city, country, region, 2 more }` + The unique ID of the shell tool call generated by the model. - The approximate location of the user. + - `output: array of BetaResponseFunctionShellCallOutputContent` - - `city: optional string` + Captured chunks of stdout and stderr output, along with their associated outcomes. - Free text input for the city of the user, e.g. `San Francisco`. + - `outcome: object { type } or object { exit_code, type }` - - `country: optional string` + The exit or timeout outcome associated with this shell call. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `Timeout object { type }` - - `region: optional string` + Indicates that the shell call exceeded its configured time limit. - Free text input for the region of the user, e.g. `California`. + - `type: "timeout"` - - `timezone: optional string` + The outcome type. Always `timeout`. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `"timeout"` - - `type: optional "approximate"` + - `Exit object { exit_code, type }` - The type of location approximation. Always `approximate`. + Indicates that the shell commands finished and returned an exit code. - - `"approximate"` + - `exit_code: number` - - `Mcp object { server_label, type, allowed_callers, 9 more }` + The exit code returned by the shell process. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `type: "exit"` - - `server_label: string` + The outcome type. Always `exit`. - A label for this MCP server, used to identify it in tool calls. + - `"exit"` - - `type: "mcp"` + - `stderr: string` - The type of the MCP tool. Always `mcp`. + Captured stderr output for the shell call. - - `"mcp"` + - `stdout: string` - - `allowed_callers: optional array of "direct" or "programmatic"` + Captured stdout output for the shell call. - The tool invocation context(s). + - `type: "shell_call_output"` - - `"direct"` + The type of the item. Always `shell_call_output`. - - `"programmatic"` + - `"shell_call_output"` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + - `id: optional string` - List of allowed tool names or a filter object. + The unique ID of the shell tool call output. Populated when this item is returned via API. - - `McpAllowedTools = array of string` + - `agent: optional object { agent_name }` - A string array of allowed tool names + The agent that produced this item. - - `McpToolFilter 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` + - `caller: optional object { type } or 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. + The execution context that produced this tool call. - - `tool_names: optional array of string` + - `Direct object { type }` - List of allowed tool names. + - `type: "direct"` - - `authorization: optional string` + The caller type. Always `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. + - `"direct"` - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + - `Program object { caller_id, 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + - `caller_id: string` - Currently supported `connector_id` values are: + The call ID of the program item that produced this tool 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` + - `type: "program"` - - `"connector_dropbox"` + The caller type. Always `program`. - - `"connector_gmail"` + - `"program"` - - `"connector_googlecalendar"` + - `max_output_length: optional number` - - `"connector_googledrive"` + The maximum number of UTF-8 characters captured for this shell call's combined output. - - `"connector_microsoftteams"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"connector_outlookcalendar"` + The status of the shell call output. - - `"connector_outlookemail"` + - `"in_progress"` - - `"connector_sharepoint"` + - `"completed"` - - `defer_loading: optional boolean` + - `"incomplete"` - Whether this MCP tool is deferred and discovered via tool search. + - `ApplyPatchCall object { call_id, operation, status, 4 more }` - - `headers: optional map[string]` + A tool call representing a request to create, delete, or update files using diff patches. - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `call_id: string` - - `require_approval: optional object { always, never } or "always" or "never"` + The unique ID of the apply patch tool call generated by the model. - Specify which of the MCP server's tools require approval. + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - - `McpToolApprovalFilter object { always, never }` + The specific create, delete, or update instruction for the apply_patch 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. + - `CreateFile object { diff, path, type }` - - `always: optional object { read_only, tool_names }` + Instruction for creating a new file via the apply_patch tool. - A filter object to specify which tools are allowed. + - `diff: string` - - `read_only: optional boolean` + Unified diff content to apply when creating 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. + - `path: string` - - `tool_names: optional array of string` + Path of the file to create relative to the workspace root. - List of allowed tool names. + - `type: "create_file"` - - `never: optional object { read_only, tool_names }` + The operation type. Always `create_file`. - A filter object to specify which tools are allowed. + - `"create_file"` - - `read_only: optional boolean` + - `DeleteFile object { path, 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. + Instruction for deleting an existing file via the apply_patch tool. - - `tool_names: optional array of string` + - `path: string` - List of allowed tool names. + Path of the file to delete relative to the workspace root. - - `McpToolApprovalSetting = "always" or "never"` + - `type: "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. + The operation type. Always `delete_file`. - - `"always"` + - `"delete_file"` - - `"never"` + - `UpdateFile object { diff, path, type }` - - `server_description: optional string` + Instruction for updating an existing file via the apply_patch tool. - Optional description of the MCP server, used to provide more context. + - `diff: string` - - `server_url: optional string` + Unified diff content to apply to the existing file. - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `path: string` - - `tunnel_id: optional string` + Path of the file to update relative to the workspace root. - 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: "update_file"` - - `CodeInterpreter object { container, type, allowed_callers }` + The operation type. Always `update_file`. - A tool that runs Python code to help generate a response to a prompt. + - `"update_file"` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + - `status: "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. + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `string` + - `"in_progress"` - The container ID. + - `"completed"` - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + - `type: "apply_patch_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 `apply_patch_call`. - - `type: "auto"` + - `"apply_patch_call"` - Always `auto`. + - `id: optional string` - - `"auto"` + The unique ID of the apply patch 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 }` - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `caller_id: string` - - `type: "code_interpreter"` + The call ID of the program item that produced this tool call. - The type of the code interpreter tool. Always `code_interpreter`. + - `type: "program"` - - `"code_interpreter"` + The caller type. Always `program`. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"program"` - The tool invocation context(s). + - `ApplyPatchCallOutput object { call_id, status, type, 4 more }` - - `"direct"` + The streamed output emitted by an apply patch tool call. - - `"programmatic"` + - `call_id: string` - - `ProgrammaticToolCalling object { type }` + The unique ID of the apply patch tool call generated by the model. - - `type: "programmatic_tool_calling"` + - `status: "completed" or "failed"` - The type of the tool. Always `programmatic_tool_calling`. + The status of the apply patch tool call output. One of `completed` or `failed`. - - `"programmatic_tool_calling"` + - `"completed"` - - `ImageGeneration object { type, action, background, 9 more }` + - `"failed"` - A tool that generates images using the GPT image models. + - `type: "apply_patch_call_output"` - - `type: "image_generation"` + The type of the item. Always `apply_patch_call_output`. - The type of the image generation tool. Always `image_generation`. + - `"apply_patch_call_output"` - - `"image_generation"` + - `id: optional string` - - `action: optional "generate" or "edit" or "auto"` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - 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"` + - `caller: optional object { type } or object { caller_id, type }` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + The execution context that produced this tool call. - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + - `Direct object { type }` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `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). + - `output: optional string` - - `file_id: optional string` + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - File ID for the mask image. + - `McpListTools object { id, server_label, tools, 3 more }` - - `image_url: optional string` + A list of tools available on an MCP server. - Base64-encoded mask image. + - `id: string` - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + The unique ID of the list. - The image generation model to use. Default: `gpt-image-1`. + - `server_label: string` - - `string` + The label of the MCP server. - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `tools: array of object { input_schema, name, annotations, description }` - The image generation model to use. Default: `gpt-image-1`. + The tools available on the server. - - `"gpt-image-1"` + - `input_schema: unknown` - - `"gpt-image-1-mini"` + The JSON schema describing the tool's input. - - `"gpt-image-2"` + - `name: string` - - `"gpt-image-2-2026-04-21"` + The name of the tool. - - `"gpt-image-1.5"` + - `annotations: optional unknown` - - `"chatgpt-image-latest"` + Additional annotations about the tool. - - `moderation: optional "auto" or "low"` + - `description: optional string` - Moderation level for the generated image. Default: `auto`. + The description of the tool. - - `"auto"` + - `type: "mcp_list_tools"` - - `"low"` + The type of the item. Always `mcp_list_tools`. - - `output_compression: optional number` + - `"mcp_list_tools"` - Compression level for the output image. Default: 100. + - `agent: optional object { agent_name }` - - `output_format: optional "png" or "webp" or "jpeg"` + The agent that produced this item. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `agent_name: string` - - `"png"` + The canonical name of the agent that produced this item. - - `"webp"` + - `error: optional string` - - `"jpeg"` + Error message if the server could not list tools. - - `partial_images: optional number` + - `McpApprovalRequest object { id, arguments, name, 3 more }` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + A request for human approval of a tool invocation. - - `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`. + The unique ID of the approval request. - - `"low"` + - `arguments: string` - - `"medium"` + A JSON string of arguments for the tool. - - `"high"` + - `name: string` - - `"auto"` + The name of the tool to run. - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `server_label: 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 label of the MCP server making the request. - - `string` + - `type: "mcp_approval_request"` - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + The type of the item. Always `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`. + - `"mcp_approval_request"` - - `"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 }` + - `McpApprovalResponse object { approval_request_id, approve, type, 3 more }` - A tool that allows the model to execute shell commands in a local environment. + A response to an MCP approval request. - - `type: "local_shell"` + - `approval_request_id: string` - The type of the local shell tool. Always `local_shell`. + The ID of the approval request being answered. - - `"local_shell"` + - `approve: boolean` - - `Shell object { type, allowed_callers, environment }` + Whether the request was approved. - A tool that allows the model to execute shell commands. + - `type: "mcp_approval_response"` - - `type: "shell"` + The type of the item. Always `mcp_approval_response`. - The type of the shell tool. Always `shell`. + - `"mcp_approval_response"` - - `"shell"` + - `id: optional string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The unique ID of the approval response - 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 }` + - `reason: optional string` - - `BetaLocalEnvironment object { type, skills }` + Optional reason for the decision. - - `BetaContainerReference object { container_id, type }` + - `McpCall object { id, arguments, name, 7 more }` - - `Custom object { name, type, allowed_callers, 3 more }` + An invocation of a tool on an MCP server. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `id: string` - - `name: string` + The unique ID of the tool call. - The name of the custom tool, used to identify it in tool calls. + - `arguments: string` - - `type: "custom"` + A JSON string of the arguments passed to the tool. - The type of the custom tool. Always `custom`. + - `name: string` - - `"custom"` + 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`. - - `defer_loading: optional boolean` + - `"mcp_call"` - Whether this tool should be deferred and discovered via tool search. + - `agent: optional object { agent_name }` - - `description: optional string` + The agent that produced this item. - 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. + - `approval_request_id: optional string` - - `Text 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. - Unconstrained free-form text. + - `error: optional string` - - `type: "text"` + The error from the tool call, if any. - Unconstrained text format. Always `text`. + - `output: optional string` - - `"text"` + The output from the tool call. - - `Grammar object { definition, syntax, type }` + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - A grammar defined by the user. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `definition: string` + - `"in_progress"` - The grammar definition. + - `"completed"` - - `syntax: "lark" or "regex"` + - `"incomplete"` - The syntax of the grammar definition. One of `lark` or `regex`. + - `"calling"` - - `"lark"` + - `"failed"` - - `"regex"` + - `CustomToolCallOutput object { call_id, output, type, 3 more }` - - `type: "grammar"` + The output of a custom tool call from your code, being sent back to the model. - Grammar format. Always `grammar`. + - `call_id: string` - - `"grammar"` + The call ID, used to map this custom tool call output to a custom tool call. - - `Namespace object { description, name, tools, type }` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - Groups function/custom tools under a shared namespace. + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `description: string` + - `StringOutput = string` - A description of the namespace shown to the model. + A string of the output of the custom tool call. - - `name: string` + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - The namespace name used in tool calls (for example, `crm`). + Text, image, or file output of the custom tool call. - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - The function/custom tools available inside this namespace. + A text input to the model. - - `Function object { name, type, allowed_callers, 5 more }` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `name: string` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `type: "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: "custom_tool_call_output"` - The tool invocation context(s). + The type of the custom tool call output. Always `custom_tool_call_output`. - - `"direct"` + - `"custom_tool_call_output"` - - `"programmatic"` + - `id: optional string` - - `defer_loading: optional boolean` + The unique ID of the custom tool call output in the OpenAI platform. - Whether this function should be deferred and discovered via tool search. + - `agent: optional object { agent_name }` - - `description: optional string` + The agent that produced this item. - - `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` + - `caller: optional object { type } or object { caller_id, type }` - - `strict: optional boolean` + The execution context that produced this tool 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. + - `Direct object { type }` - - `Custom object { name, type, allowed_callers, 3 more }` + - `type: "direct"` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The caller type. Always `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"` + The caller type. Always `program`. - The tool invocation context(s). + - `"program"` - - `"direct"` + - `CustomToolCall object { call_id, input, name, 5 more }` - - `"programmatic"` + A call to a custom tool created by the model. - - `defer_loading: optional boolean` + - `call_id: string` - Whether this tool should be deferred and discovered via tool search. + An identifier used to map this custom tool call to a tool call output. - - `description: optional string` + - `input: string` - Optional description of the custom tool, used to provide more context. + The input for the custom tool call generated by the model. - - `format: optional object { type } or object { definition, syntax, type }` + - `name: string` - The input format for the custom tool. Default is unconstrained text. + The name of the custom tool being called. - - `Text object { type }` + - `type: "custom_tool_call"` - Unconstrained free-form text. + The type of the custom tool call. Always `custom_tool_call`. - - `type: "text"` + - `"custom_tool_call"` - Unconstrained text format. Always `text`. + - `id: optional string` - - `"text"` + The unique ID of the custom tool call in the OpenAI platform. - - `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"` + - `"direct"` - Grammar format. Always `grammar`. + - `Program object { caller_id, type }` - - `"grammar"` + - `caller_id: string` - - `type: "namespace"` + The call ID of the program item that produced this tool call. - The type of the tool. Always `namespace`. + - `type: "program"` - - `"namespace"` + - `"program"` - - `ToolSearch object { type, description, execution, parameters }` + - `namespace: optional string` - Hosted or BYOT tool search configuration for deferred tools. + The namespace of the custom tool being called. - - `type: "tool_search"` + - `CompactionTrigger object { type, agent }` - The type of the tool. Always `tool_search`. + Compacts the current context. Must be the final input item. - - `"tool_search"` + - `type: "compaction_trigger"` - - `description: optional string` + The type of the item. Always `compaction_trigger`. - Description shown to the model for a client-executed tool search tool. + - `"compaction_trigger"` - - `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` + - `ItemReference object { id, agent, type }` - Parameter schema for a client-executed tool search tool. + An internal identifier for an item to reference. - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + - `id: string` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The ID of the item to reference. - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `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"` + - `type: optional "item_reference"` - - `"text"` + The type of item to reference. Always `item_reference`. - - `"image"` + - `"item_reference"` - - `search_context_size: optional "low" or "medium" or "high"` + - `Program object { id, call_id, code, 3 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 this program item. - - `"medium"` + - `call_id: string` - - `"high"` + The stable call ID of the program item. - - `user_location: optional object { type, city, country, 2 more }` + - `code: string` - The user's location. + The JavaScript source executed by programmatic tool calling. - - `type: "approximate"` + - `fingerprint: string` - The type of location approximation. Always `approximate`. + Opaque program replay fingerprint that must be round-tripped. - - `"approximate"` + - `type: "program"` - - `city: optional string` + The item type. Always `program`. - Free text input for the city of the user, e.g. `San Francisco`. + - `"program"` - - `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` + - `ProgramOutput object { id, call_id, result, 3 more }` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `id: string` - - `ApplyPatch object { type, allowed_callers }` + The unique ID of this program output item. - Allows the assistant to create, delete, or update files using unified diffs. + - `call_id: string` - - `type: "apply_patch"` + The call ID of the program item. - The type of the tool. Always `apply_patch`. + - `result: string` - - `"apply_patch"` + 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. - - `"direct"` + - `"completed"` - - `"programmatic"` + - `"incomplete"` - - `type: "tool_search_output"` + - `type: "program_output"` - The type of the item. Always `tool_search_output`. + The item type. Always `program_output`. - - `"tool_search_output"` + - `"program_output"` - `agent: optional object { agent_name }` @@ -107079,1051 +105521,1043 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `created_by: optional string` + - `metadata: map[string]` - 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. - - `AdditionalTools object { id, role, tools, 2 more }` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `id: string` + - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` - The unique ID of the additional tools item. + 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. - - `role: "unknown" or "user" or "assistant" or 5 more` + - `"gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more` - The role that provided the additional tools. + 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. - - `"unknown"` + - `"gpt-5.6-sol"` - - `"user"` + - `"gpt-5.6-terra"` - - `"assistant"` + - `"gpt-5.6-luna"` - - `"system"` + - `"gpt-5.4"` - - `"critic"` + - `"gpt-5.4-mini"` - - `"discriminator"` + - `"gpt-5.4-nano"` - - `"developer"` + - `"gpt-5.4-mini-2026-03-17"` - - `"tool"` + - `"gpt-5.4-nano-2026-03-17"` - - `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.3-chat-latest"` - The additional tool definitions made available at this item. + - `"gpt-5.2"` - - `Function object { name, parameters, strict, 5 more }` + - `"gpt-5.2-2025-12-11"` - 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.2-chat-latest"` - - `name: string` + - `"gpt-5.2-pro"` - The name of the function to call. + - `"gpt-5.2-pro-2025-12-11"` - - `parameters: map[unknown]` + - `"gpt-5.1"` - A JSON schema object describing the parameters of the function. + - `"gpt-5.1-2025-11-13"` - - `strict: boolean` + - `"gpt-5.1-codex"` - Whether strict parameter validation is enforced for this function tool. + - `"gpt-5.1-mini"` - - `type: "function"` + - `"gpt-5.1-chat-latest"` - The type of the function tool. Always `function`. + - `"gpt-5"` - - `"function"` + - `"gpt-5-mini"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"gpt-5-nano"` - The tool invocation context(s). + - `"gpt-5-2025-08-07"` - - `"direct"` + - `"gpt-5-mini-2025-08-07"` - - `"programmatic"` + - `"gpt-5-nano-2025-08-07"` - - `defer_loading: optional boolean` + - `"gpt-5-chat-latest"` - Whether this function is deferred and loaded via tool search. + - `"gpt-4.1"` - - `description: optional string` + - `"gpt-4.1-mini"` - A description of the function. Used by the model to determine whether or not to call the function. + - `"gpt-4.1-nano"` - - `output_schema: optional map[unknown]` + - `"gpt-4.1-2025-04-14"` - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `"gpt-4.1-mini-2025-04-14"` - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + - `"gpt-4.1-nano-2025-04-14"` - 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). + - `"o4-mini"` - - `type: "file_search"` + - `"o4-mini-2025-04-16"` - The type of the file search tool. Always `file_search`. + - `"o3"` - - `"file_search"` + - `"o3-2025-04-16"` - - `vector_store_ids: array of string` + - `"o3-mini"` - The IDs of the vector stores to search. + - `"o3-mini-2025-01-31"` - - `filters: optional object { key, type, value } or object { filters, type }` + - `"o1"` - A filter to apply. + - `"o1-2024-12-17"` - - `ComparisonFilter object { key, type, value }` + - `"o1-preview"` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `"o1-preview-2024-09-12"` - - `key: string` + - `"o1-mini"` - The key to compare against the value. + - `"o1-mini-2024-09-12"` - - `type: "eq" or "ne" or "gt" or 5 more` + - `"gpt-4o"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `"gpt-4o-2024-11-20"` - - `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-4o-2024-08-06"` - - `"eq"` + - `"gpt-4o-2024-05-13"` - - `"ne"` + - `"gpt-4o-audio-preview"` - - `"gt"` + - `"gpt-4o-audio-preview-2024-10-01"` - - `"gte"` + - `"gpt-4o-audio-preview-2024-12-17"` - - `"lt"` + - `"gpt-4o-audio-preview-2025-06-03"` - - `"lte"` + - `"gpt-4o-mini-audio-preview"` - - `"in"` + - `"gpt-4o-mini-audio-preview-2024-12-17"` - - `"nin"` + - `"gpt-4o-search-preview"` - - `value: string or number or boolean or array of string or number` + - `"gpt-4o-mini-search-preview"` - The value to compare against the attribute key; supports string, number, or boolean types. + - `"gpt-4o-search-preview-2025-03-11"` - - `string` + - `"gpt-4o-mini-search-preview-2025-03-11"` - - `number` + - `"chatgpt-4o-latest"` - - `boolean` + - `"codex-mini-latest"` - - `array of string or number` + - `"gpt-4o-mini"` - - `string` + - `"gpt-4o-mini-2024-07-18"` - - `number` + - `"gpt-4-turbo"` - - `CompoundFilter object { filters, type }` + - `"gpt-4-turbo-2024-04-09"` - Combine multiple filters using `and` or `or`. + - `"gpt-4-0125-preview"` - - `filters: array of object { key, type, value } or unknown` + - `"gpt-4-turbo-preview"` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `"gpt-4-1106-preview"` - - `ComparisonFilter object { key, type, value }` + - `"gpt-4-vision-preview"` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `"gpt-4"` - - `key: string` + - `"gpt-4-0314"` - The key to compare against the value. + - `"gpt-4-0613"` - - `type: "eq" or "ne" or "gt" or 5 more` + - `"gpt-4-32k"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `"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"` - - `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-3.5-turbo-1106"` - - `"eq"` + - `"gpt-3.5-turbo-0125"` - - `"ne"` + - `"gpt-3.5-turbo-16k-0613"` - - `"gt"` + - `"o1-pro"` - - `"gte"` + - `"o1-pro-2025-03-19"` - - `"lt"` + - `"o3-pro"` - - `"lte"` + - `"o3-pro-2025-06-10"` - - `"in"` + - `"o3-deep-research"` - - `"nin"` + - `"o3-deep-research-2025-06-26"` - - `value: string or number or boolean or array of string or number` + - `"o4-mini-deep-research"` - The value to compare against the attribute key; supports string, number, or boolean types. + - `"o4-mini-deep-research-2025-06-26"` - - `string` + - `"computer-use-preview"` - - `number` + - `"computer-use-preview-2025-03-11"` - - `boolean` + - `"gpt-5-codex"` - - `array of string or number` + - `"gpt-5-pro"` - - `string` + - `"gpt-5-pro-2025-10-06"` - - `number` + - `"gpt-5.1-codex-max"` - - `unknown` + - `string` - - `type: "and" or "or"` + - `object: "response"` - Type of operation: `and` or `or`. + The object type of this resource - always set to `response`. - - `"and"` + - `"response"` - - `"or"` + - `output: array of BetaResponseOutputItem` - - `max_num_results: optional number` + An array of content items generated by the model. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - 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. - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `BetaResponseOutputMessage object { id, content, role, 4 more }` - Ranking options for search. + An output message from the model. - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `FileSearchCall object { id, queries, status, 3 more }` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + The results of a file search tool call. See the + [file search guide](/docs/guides/tools-file-search) for more information. - - `embedding_weight: number` + - `id: string` - The weight of the embedding in the reciprocal ranking fusion. + The unique ID of the file search tool call. - - `text_weight: number` + - `queries: array of string` - The weight of the text in the reciprocal ranking fusion. + The queries used to search for files. - - `ranker: optional "auto" or "default-2024-11-15"` + - `status: "in_progress" or "searching" or "completed" or 2 more` - The ranker to use for the file search. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `"auto"` + - `"in_progress"` - - `"default-2024-11-15"` + - `"searching"` - - `score_threshold: optional number` + - `"completed"` - 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. + - `"incomplete"` - - `Computer object { type }` + - `"failed"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `type: "file_search_call"` - - `type: "computer"` + The type of the file search tool call. Always `file_search_call`. - The type of the computer tool. Always `computer`. + - `"file_search_call"` - - `"computer"` + - `agent: optional object { agent_name }` - - `ComputerUsePreview object { display_height, display_width, environment, 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` - - `display_height: number` + The canonical name of the agent that produced this item. - The height of the computer display. + - `results: optional array of object { attributes, file_id, filename, 2 more }` - - `display_width: number` + The results of the file search tool call. - The width of the computer display. + - `attributes: optional map[string or number or boolean]` - - `environment: "windows" or "mac" or "linux" or 2 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. - The type of computer environment to control. + - `string` - - `"windows"` + - `number` - - `"mac"` + - `boolean` - - `"linux"` + - `file_id: optional string` - - `"ubuntu"` + The unique ID of the file. - - `"browser"` + - `filename: optional string` - - `type: "computer_use_preview"` + The name of the file. - The type of the computer use tool. Always `computer_use_preview`. + - `score: optional number` - - `"computer_use_preview"` + The relevance score of the file - a value between 0 and 1. - - `WebSearch object { type, filters, search_context_size, user_location }` + - `text: optional string` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The text that was retrieved from the file. - - `type: "web_search" or "web_search_2025_08_26"` + - `FunctionCall object { arguments, call_id, name, 6 more }` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. - - `"web_search"` + - `arguments: string` - - `"web_search_2025_08_26"` + A JSON string of the arguments to pass to the function. - - `filters: optional object { allowed_domains }` + - `call_id: string` - Filters for the search. + The unique ID of the function tool call generated by the model. - - `allowed_domains: optional array of string` + - `name: string` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + The name of the function to run. - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `type: "function_call"` - - `search_context_size: optional "low" or "medium" or "high"` + The type of the function tool call. Always `function_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. + - `"function_call"` - - `"low"` + - `id: optional string` - - `"medium"` + The unique ID of the function tool call. - - `"high"` + - `agent: optional object { agent_name }` - - `user_location: optional object { city, country, region, 2 more }` + The agent that produced this item. - 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`. + - `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` - - `type: optional "approximate"` + The call ID of the program item that produced this tool call. - The type of location approximation. Always `approximate`. + - `type: "program"` - - `"approximate"` + - `"program"` - - `Mcp object { server_label, type, allowed_callers, 9 more }` + - `namespace: optional string` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + The namespace of the function to run. - - `server_label: string` + - `status: optional "in_progress" or "completed" or "incomplete"` - A label for this MCP server, used to identify it in tool calls. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `type: "mcp"` + - `"in_progress"` - The type of the MCP tool. Always `mcp`. + - `"completed"` - - `"mcp"` + - `"incomplete"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `FunctionCallOutput object { id, call_id, output, 5 more }` - The tool invocation context(s). + - `id: string` - - `"direct"` + The unique ID of the function call tool output. - - `"programmatic"` + - `call_id: string` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + The unique ID of the function tool call generated by the model. - List of allowed tool names or a filter object. + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `McpAllowedTools = array of string` + The output from the function call generated by your code. + Can be a string or an list of output content. - A string array of allowed tool names + - `StringOutput = string` - - `McpToolFilter object { read_only, tool_names }` + A string of the output of the function call. - A filter object to specify which tools are allowed. + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `read_only: optional boolean` + Text, image, or file output of the function 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. + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `tool_names: optional array of string` + A text input to the model. - List of allowed tool names. + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `authorization: optional string` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - 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. + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + A file input to the model. - 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](https://platform.openai.com/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: "function_call_output"` - - `"connector_googledrive"` + The type of the function tool call output. Always `function_call_output`. - - `"connector_microsoftteams"` + - `"function_call_output"` - - `"connector_outlookcalendar"` + - `agent: optional object { agent_name }` - - `"connector_outlookemail"` + The agent that produced this item. - - `"connector_sharepoint"` + - `agent_name: string` - - `defer_loading: optional boolean` + The canonical name of the agent that produced this item. - Whether this MCP tool is deferred and discovered via tool search. + - `caller: optional object { type } or object { caller_id, type }` - - `headers: optional map[string]` + The execution context that produced this tool call. - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `Direct object { type }` - - `require_approval: optional object { always, never } or "always" or "never"` + - `type: "direct"` - Specify which of the MCP server's tools require approval. + The caller type. Always `direct`. - - `McpToolApprovalFilter object { always, never }` + - `"direct"` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `Program object { caller_id, type }` - - `always: optional 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. + The caller type. Always `program`. - - `tool_names: optional array of string` + - `"program"` - List of allowed tool names. + - `created_by: optional string` - - `never: optional object { read_only, tool_names }` + The identifier of the actor that created the item. - A filter object to specify which tools are allowed. + - `AgentMessage object { id, author, content, 3 more }` - - `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 agent message. - - `tool_names: optional array of string` + - `author: string` - List of allowed tool names. + The sending agent identity. - - `McpToolApprovalSetting = "always" or "never"` + - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 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. + Encrypted content sent between agents. - - `"always"` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `"never"` + A text input to the model. - - `server_description: optional string` + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - Optional description of the MCP server, used to provide more context. + A text output from the model. - - `server_url: optional string` + - `Text object { text, type }` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + A text content. - - `tunnel_id: optional string` + - `text: 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. + - `type: "text"` - - `CodeInterpreter object { container, type, allowed_callers }` + - `"text"` - A tool that runs Python code to help generate a response to a prompt. + - `SummaryText object { text, type }` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + A summary 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` + A summary of the reasoning output from the model so far. - The container ID. + - `type: "summary_text"` - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + The type of the object. Always `summary_text`. - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `"summary_text"` - - `type: "auto"` + - `ReasoningText object { text, type }` - Always `auto`. + Reasoning text from the model. - - `"auto"` + - `text: string` - - `file_ids: optional array of string` + The reasoning text from the model. - An optional list of uploaded files to make available to your code. + - `type: "reasoning_text"` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + The type of the reasoning text. Always `reasoning_text`. - The memory limit for the code interpreter container. + - `"reasoning_text"` - - `"1g"` + - `BetaResponseOutputRefusal object { refusal, type }` - - `"4g"` + A refusal from the model. - - `"16g"` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `"64g"` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` - Network access policy for the container. + A screenshot of a computer. - - `BetaContainerNetworkPolicyDisabled object { type }` + - `detail: "low" or "high" or "auto" or "original"` - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `type: "code_interpreter"` + - `"low"` - The type of the code interpreter tool. Always `code_interpreter`. + - `"high"` - - `"code_interpreter"` + - `"auto"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"original"` - The tool invocation context(s). + - `file_id: string` - - `"direct"` + The identifier of an uploaded file that contains the screenshot. - - `"programmatic"` + - `image_url: string` - - `ProgrammaticToolCalling object { type }` + The URL of the screenshot image. - - `type: "programmatic_tool_calling"` + - `type: "computer_screenshot"` - The type of the tool. Always `programmatic_tool_calling`. + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `"programmatic_tool_calling"` + - `"computer_screenshot"` - - `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"` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - Whether to generate a new image or edit an existing image. Default: `auto`. + A file input to the model. - - `"generate"` + - `EncryptedContent object { encrypted_content, type }` - - `"edit"` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `"auto"` + - `encrypted_content: string` - - `background: optional "transparent" or "opaque" or "auto"` + Opaque encrypted content. - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + - `type: "encrypted_content"` - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + The type of the input item. Always `encrypted_content`. - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `"encrypted_content"` - - `"transparent"` + - `recipient: string` - - `"opaque"` + The destination agent identity. - - `"auto"` + - `type: "agent_message"` - - `input_fidelity: optional "high" or "low"` + The type of the item. Always `agent_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`. + - `"agent_message"` - - `"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` + - `MultiAgentCall object { id, action, arguments, 3 more }` - File ID for the mask image. + - `id: string` - - `image_url: optional string` + The unique ID of the multi-agent call item. - Base64-encoded mask image. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + The multi-agent action to execute. - The image generation model to use. Default: `gpt-image-1`. + - `"spawn_agent"` - - `string` + - `"interrupt_agent"` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `"list_agents"` - The image generation model to use. Default: `gpt-image-1`. + - `"send_message"` - - `"gpt-image-1"` + - `"followup_task"` - - `"gpt-image-1-mini"` + - `"wait_agent"` - - `"gpt-image-2"` + - `arguments: string` - - `"gpt-image-2-2026-04-21"` + The JSON string of arguments generated for the action. - - `"gpt-image-1.5"` + - `call_id: string` - - `"chatgpt-image-latest"` + The unique ID linking this call to its output. - - `moderation: optional "auto" or "low"` + - `type: "multi_agent_call"` - Moderation level for the generated image. Default: `auto`. + The type of the multi-agent call. Always `multi_agent_call`. - - `"auto"` + - `"multi_agent_call"` - - `"low"` + - `agent: optional object { agent_name }` - - `output_compression: optional number` + The agent that produced this item. - Compression level for the output image. Default: 100. + - `agent_name: string` - - `output_format: optional "png" or "webp" or "jpeg"` + The canonical name of the agent that produced this item. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `MultiAgentCallOutput object { id, action, call_id, 3 more }` - - `"png"` + - `id: string` - - `"webp"` + The unique ID of the multi-agent call output item. - - `"jpeg"` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `partial_images: optional number` + The multi-agent action that produced this result. - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `"spawn_agent"` - - `quality: optional "low" or "medium" or "high" or "auto"` + - `"interrupt_agent"` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `"list_agents"` - - `"low"` + - `"send_message"` - - `"medium"` + - `"followup_task"` - - `"high"` + - `"wait_agent"` - - `"auto"` + - `call_id: string` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + The unique ID of the multi-agent 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`. + - `output: array of BetaResponseOutputText` - - `string` + Text output returned by the multi-agent action. - - `"1024x1024" or "1024x1536" or "1536x1024" or "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 }` - 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 annotations of the text output. - - `"1024x1024"` + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - - `"1024x1536"` + - `text: string` - - `"1536x1024"` + The text output from the model. - - `"auto"` + - `type: "output_text"` - - `LocalShell object { type }` + The type of the output text. Always `output_text`. - A tool that allows the model to execute shell commands in a local environment. + - `type: "multi_agent_call_output"` - - `type: "local_shell"` + The type of the multi-agent result. Always `multi_agent_call_output`. - The type of the local shell tool. Always `local_shell`. + - `"multi_agent_call_output"` - - `"local_shell"` + - `agent: optional object { agent_name }` - - `Shell object { type, allowed_callers, environment }` + The agent that produced this item. - A tool that allows the model to execute shell commands. + - `agent_name: string` - - `type: "shell"` + The canonical name of the agent that produced this item. - The type of the shell tool. Always `shell`. + - `WebSearchCall object { id, action, status, 2 more }` - - `"shell"` + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `id: string` - The tool invocation context(s). + The unique ID of the web search tool call. - - `"direct"` + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - - `"programmatic"` + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + - `Search object { type, queries, query, sources }` - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + Action type "search" - Performs a web search query. - - `BetaLocalEnvironment object { type, skills }` + - `type: "search"` - - `BetaContainerReference object { container_id, type }` + The action type. - - `Custom object { name, type, allowed_callers, 3 more }` + - `"search"` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `queries: optional array of string` - - `name: string` + The search queries. - The name of the custom tool, used to identify it in tool calls. + - `query: optional string` - - `type: "custom"` + The search query. - The type of the custom tool. Always `custom`. + - `sources: optional array of object { type, url }` - - `"custom"` + The sources used in the search. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `type: "url"` - The tool invocation context(s). + The type of source. Always `url`. - - `"direct"` + - `"url"` - - `"programmatic"` + - `url: string` - - `defer_loading: optional boolean` + The URL of the source. - Whether this tool should be deferred and discovered via tool search. + - `OpenPage object { type, url }` - - `description: optional string` + Action type "open_page" - Opens a specific URL from search results. - Optional description of the custom tool, used to provide more context. + - `type: "open_page"` - - `format: optional object { type } or object { definition, syntax, type }` + The action type. - The input format for the custom tool. Default is unconstrained text. + - `"open_page"` - - `Text object { type }` + - `url: optional string` - Unconstrained free-form text. + The URL opened by the model. - - `type: "text"` + - `FindInPage object { pattern, type, url }` - Unconstrained text format. Always `text`. + Action type "find_in_page": Searches for a pattern within a loaded page. - - `"text"` + - `pattern: string` - - `Grammar object { definition, syntax, type }` + The pattern or text to search for within the page. - A grammar defined by the user. + - `type: "find_in_page"` - - `definition: string` + The action type. - The grammar definition. + - `"find_in_page"` - - `syntax: "lark" or "regex"` + - `url: string` - The syntax of the grammar definition. One of `lark` or `regex`. + The URL of the page searched for the pattern. - - `"lark"` + - `status: "in_progress" or "searching" or "completed" or "failed"` - - `"regex"` + The status of the web search tool call. - - `type: "grammar"` + - `"in_progress"` - Grammar format. Always `grammar`. + - `"searching"` - - `"grammar"` + - `"completed"` - - `Namespace object { description, name, tools, type }` + - `"failed"` - Groups function/custom tools under a shared namespace. + - `type: "web_search_call"` - - `description: string` + The type of the web search tool call. Always `web_search_call`. - A description of the namespace shown to the model. + - `"web_search_call"` - - `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 }` + - `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. - - `type: "function"` + - `id: string` - - `"function"` + The unique ID of the computer call. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `call_id: string` - The tool invocation context(s). + An identifier used when responding to the tool call with output. - - `"direct"` + - `pending_safety_checks: array of object { id, code, message }` - - `"programmatic"` + The pending safety checks for the computer call. - - `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` + - `status: "in_progress" or "completed" or "incomplete"` - 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 status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `Custom object { name, type, allowed_callers, 3 more }` + - `"in_progress"` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `"completed"` - - `name: string` + - `"incomplete"` - The name of the custom tool, used to identify it in tool calls. + - `type: "computer_call"` - - `type: "custom"` + The type of the computer call. Always `computer_call`. - The type of the custom tool. Always `custom`. + - `"computer_call"` - - `"custom"` + - `action: optional BetaComputerAction` - - `allowed_callers: optional array of "direct" or "programmatic"` + A click action. - The tool invocation context(s). + - `actions: optional BetaComputerActionList` - - `"direct"` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `"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. + - `ComputerCallOutput object { id, call_id, output, 5 more }` - - `format: optional object { type } or object { definition, syntax, type }` + - `id: string` - The input format for the custom tool. Default is unconstrained text. + The unique ID of the computer call tool output. - - `Text object { type }` + - `call_id: string` - Unconstrained free-form text. + The ID of the computer tool call that produced the output. - - `type: "text"` + - `output: BetaResponseComputerToolCallOutputScreenshot` - Unconstrained text format. Always `text`. + A computer screenshot image used with the computer use tool. - - `"text"` + - `status: "completed" or "incomplete" or "failed" or "in_progress"` - - `Grammar object { definition, syntax, type }` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - A grammar defined by the user. + - `"completed"` - - `definition: string` + - `"incomplete"` - The grammar definition. + - `"failed"` - - `syntax: "lark" or "regex"` + - `"in_progress"` - The syntax of the grammar definition. One of `lark` or `regex`. + - `type: "computer_call_output"` - - `"lark"` + The type of the computer tool call output. Always `computer_call_output`. - - `"regex"` + - `"computer_call_output"` - - `type: "grammar"` + - `acknowledged_safety_checks: optional array of object { id, code, message }` - Grammar format. Always `grammar`. + The safety checks reported by the API that have been acknowledged by the + developer. - - `"grammar"` + - `id: string` - - `type: "namespace"` + The ID of the pending safety check. - The type of the tool. Always `namespace`. + - `code: optional string` - - `"namespace"` + The type of the pending safety check. - - `ToolSearch object { type, description, execution, parameters }` + - `message: optional string` - Hosted or BYOT tool search configuration for deferred tools. + Details about the pending safety check. - - `type: "tool_search"` + - `agent: optional object { agent_name }` - The type of the tool. Always `tool_search`. + The agent that produced this item. - - `"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. + - `created_by: optional string` - - `execution: optional "server" or "client"` + The identifier of the actor that created the item. - Whether tool search is executed by the server or by the client. + - `Reasoning object { id, summary, type, 4 more }` - - `"server"` + 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). - - `"client"` + - `id: string` - - `parameters: optional unknown` + The unique identifier of the reasoning content. - Parameter schema for a client-executed tool search tool. + - `summary: array of object { text, type }` - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + Reasoning summary content. - 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). + - `text: string` - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + A summary of the reasoning output from the model so far. - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `type: "summary_text"` - - `"web_search_preview"` + The type of the object. Always `summary_text`. - - `"web_search_preview_2025_03_11"` + - `"summary_text"` - - `search_content_types: optional array of "text" or "image"` + - `type: "reasoning"` - - `"text"` + The type of the object. Always `reasoning`. - - `"image"` + - `"reasoning"` - - `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"` + - `content: optional array of object { text, type }` - - `user_location: optional object { type, city, country, 2 more }` + Reasoning text content. - The user's location. + - `text: string` - - `type: "approximate"` + The reasoning text from the model. - The type of location approximation. Always `approximate`. + - `type: "reasoning_text"` - - `"approximate"` + The type of the reasoning text. Always `reasoning_text`. - - `city: optional string` + - `"reasoning_text"` - Free text input for the city of the user, e.g. `San Francisco`. + - `encrypted_content: optional string` - - `country: optional string` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `region: optional string` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Free text input for the region of the user, e.g. `California`. + - `"in_progress"` - - `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 }` + - `Program object { id, call_id, code, 3 more }` - Allows the assistant to create, delete, or update files using unified diffs. + - `id: string` - - `type: "apply_patch"` + The unique ID of the program item. - The type of the tool. Always `apply_patch`. + - `call_id: string` - - `"apply_patch"` + The stable call ID of the program item. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `code: string` - The tool invocation context(s). + The JavaScript source executed by programmatic tool calling. - - `"direct"` + - `fingerprint: string` - - `"programmatic"` + Opaque program replay fingerprint that must be round-tripped. - - `type: "additional_tools"` + - `type: "program"` - The type of the item. Always `additional_tools`. + The type of the item. Always `program`. - - `"additional_tools"` + - `"program"` - `agent: optional object { agent_name }` @@ -108133,23 +106567,33 @@ 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](https://platform.openai.com/docs/api-reference/responses/compact). + - `ProgramOutput object { id, call_id, result, 3 more }` - `id: string` - The unique ID of the compaction item. + The unique ID of the program output item. - - `encrypted_content: string` + - `call_id: string` - The encrypted content that was produced by compaction. + The call ID of the program item. - - `type: "compaction"` + - `result: string` - The type of the item. Always `compaction`. + The result produced by the program item. - - `"compaction"` + - `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 }` @@ -108159,39 +106603,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` + - `ToolSearchCall object { id, arguments, call_id, 5 more }` - The identifier of the actor that created the item. + - `id: string` - - `ImageGenerationCall object { id, result, status, 2 more }` + The unique ID of the tool search call item. - An image generation request made by the model. + - `arguments: unknown` - - `id: string` + Arguments used for the tool search call. - The unique ID of the image generation call. + - `call_id: string` - - `result: string` + The unique ID of the tool search call generated by the model. - The generated image encoded in base64. + - `execution: "server" or "client"` - - `status: "in_progress" or "completed" or "generating" or "failed"` + Whether tool search was executed by the server or by the client. - The status of the image generation call. + - `"server"` + + - `"client"` + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the tool search call item that was recorded. - `"in_progress"` - `"completed"` - - `"generating"` - - - `"failed"` + - `"incomplete"` - - `type: "image_generation_call"` + - `type: "tool_search_call"` - The type of the image generation call. Always `image_generation_call`. + The type of the item. Always `tool_search_call`. - - `"image_generation_call"` + - `"tool_search_call"` - `agent: optional object { agent_name }` @@ -108201,1090 +106649,1078 @@ 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. + - `created_by: optional string` - - `outputs: array of object { logs, type } or object { type, url }` + The identifier of the actor that created the item. - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `ToolSearchOutput object { id, call_id, execution, 5 more }` - - `Logs object { logs, type }` + - `id: string` - The logs output from the code interpreter. + The unique ID of the tool search output item. - - `logs: string` + - `call_id: string` - The logs output from the code interpreter. + The unique ID of the tool search call generated by the model. - - `type: "logs"` + - `execution: "server" or "client"` - The type of the output. Always `logs`. + Whether tool search was executed by the server or by the client. - - `"logs"` + - `"server"` - - `Image object { type, url }` + - `"client"` - The image output from the code interpreter. + - `status: "in_progress" or "completed" or "incomplete"` - - `type: "image"` + The status of the tool search output item that was recorded. - The type of the output. Always `image`. + - `"in_progress"` - - `"image"` + - `"completed"` - - `url: string` + - `"incomplete"` - The URL of the image output from the code interpreter. + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + The loaded tool definitions returned by tool search. - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `Function object { name, parameters, strict, 5 more }` - - `"in_progress"` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `"completed"` + - `name: string` - - `"incomplete"` + The name of the function to call. - - `"interpreting"` + - `parameters: map[unknown]` - - `"failed"` + A JSON schema object describing the parameters of the function. - - `type: "code_interpreter_call"` + - `strict: boolean` - The type of the code interpreter tool call. Always `code_interpreter_call`. + Whether strict parameter validation is enforced for this function tool. - - `"code_interpreter_call"` + - `type: "function"` - - `agent: optional object { agent_name }` + The type of the function tool. Always `function`. - The agent that produced this item. + - `"function"` - - `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` + - `defer_loading: optional boolean` - The unique ID of the local shell call. + Whether this function is deferred and loaded via tool search. - - `action: object { command, env, type, 3 more }` + - `description: optional string` - Execute a shell command on the server. + A description of the function. Used by the model to determine whether or not to call the function. - - `command: array of string` + - `output_schema: optional map[unknown]` - The command to run. + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `env: map[string]` + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - Environment variables to set for the command. + 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: "exec"` + - `type: "file_search"` - The type of the local shell action. Always `exec`. + The type of the file search tool. Always `file_search`. - - `"exec"` + - `"file_search"` - - `timeout_ms: optional number` + - `vector_store_ids: array of string` - Optional timeout in milliseconds for the command. + The IDs of the vector stores to search. - - `user: optional string` + - `filters: optional object { key, type, value } or object { filters, type }` - Optional user to run the command as. + A filter to apply. - - `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`. + - `CompoundFilter object { filters, type }` - - `"local_shell_call_output"` + Combine multiple filters using `and` or `or`. - - `agent: optional object { agent_name }` + - `filters: array of object { key, type, value } or unknown` - The agent that produced this item. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `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 { id, action, call_id, 6 more }` + - `"eq"` - A tool call that executes one or more shell commands in a managed environment. + - `"ne"` - - `id: string` + - `"gt"` - The unique ID of the shell tool call. Populated when this item is returned via API. + - `"gte"` - - `action: object { commands, max_output_length, timeout_ms }` + - `"lt"` - The shell commands and limits that describe how to run the tool call. + - `"lte"` - - `commands: array of string` + - `"in"` - - `max_output_length: number` + - `"nin"` - Optional maximum number of characters to return from each command. + - `value: string or number or boolean or array of string or number` - - `timeout_ms: number` + The value to compare against the attribute key; supports string, number, or boolean types. - Optional timeout in milliseconds for the commands. + - `string` - - `call_id: string` + - `number` - The unique ID of the shell tool call generated by the model. + - `boolean` - - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` + - `array of string or number` - Represents the use of a local environment to perform shell actions. + - `string` - - `BetaResponseLocalEnvironment object { type }` + - `number` - Represents the use of a local environment to perform shell actions. + - `unknown` - - `type: "local"` + - `type: "and" or "or"` - The environment type. Always `local`. + Type of operation: `and` or `or`. - - `"local"` + - `"and"` - - `BetaResponseContainerReference object { container_id, type }` + - `"or"` - Represents a container created with /v1/containers. + - `max_num_results: optional number` - - `container_id: string` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `type: "container_reference"` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - The environment type. Always `container_reference`. + Ranking options for search. - - `"container_reference"` + - `hybrid_search: optional object { embedding_weight, text_weight }` - - `status: "in_progress" or "completed" or "incomplete"` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `embedding_weight: number` - - `"in_progress"` + 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. - - `type: "shell_call"` + - `ranker: optional "auto" or "default-2024-11-15"` - The type of the item. Always `shell_call`. + The ranker to use for the file search. - - `"shell_call"` + - `"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 }` - - `caller: optional object { type } or 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). - The execution context that produced this tool call. + - `type: "computer"` - - `Direct object { type }` + The type of the computer tool. Always `computer`. - - `type: "direct"` + - `"computer"` - - `"direct"` + - `ComputerUsePreview object { display_height, display_width, environment, 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` + - `display_height: number` - The call ID of the program item that produced this tool call. + The height of the computer display. - - `type: "program"` + - `display_width: number` - - `"program"` + The width of the computer display. - - `created_by: optional string` + - `environment: "windows" or "mac" or "linux" or 2 more` - The ID of the entity that created this tool call. + The type of computer environment to control. - - `ShellCallOutput object { id, call_id, max_output_length, 6 more }` + - `"windows"` - The output of a shell tool call that was emitted. + - `"mac"` - - `id: string` + - `"linux"` - The unique ID of the shell call output. Populated when this item is returned via API. + - `"ubuntu"` - - `call_id: string` + - `"browser"` - The unique ID of the shell tool call generated by the model. + - `type: "computer_use_preview"` - - `max_output_length: number` + The type of the computer use tool. Always `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. + - `"computer_use_preview"` - - `output: array of object { outcome, stderr, stdout, created_by }` + - `WebSearch object { type, filters, search_context_size, user_location }` - An array of shell call output contents + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - - `outcome: object { type } or object { exit_code, type }` + - `type: "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. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `Timeout object { type }` + - `"web_search"` - Indicates that the shell call exceeded its configured time limit. + - `"web_search_2025_08_26"` - - `type: "timeout"` + - `filters: optional object { allowed_domains }` - The outcome type. Always `timeout`. + Filters for the search. - - `"timeout"` + - `allowed_domains: optional array of string` - - `Exit object { exit_code, type }` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - Indicates that the shell commands finished and returned an exit code. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `exit_code: number` + - `search_context_size: optional "low" or "medium" or "high"` - Exit code from the shell process. + 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: "exit"` + - `"low"` - The outcome type. Always `exit`. + - `"medium"` - - `"exit"` + - `"high"` - - `stderr: string` + - `user_location: optional object { city, country, region, 2 more }` - The standard error output that was captured. + The approximate location of the user. - - `stdout: string` + - `city: optional string` - The standard output that was captured. + Free text input for the city of the user, e.g. `San Francisco`. - - `created_by: optional string` + - `country: optional string` - The identifier of the actor that created the item. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `status: "in_progress" or "completed" or "incomplete"` + - `region: optional string` - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + Free text input for the region of the user, e.g. `California`. - - `"in_progress"` + - `timezone: optional string` - - `"completed"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `"incomplete"` + - `type: optional "approximate"` - - `type: "shell_call_output"` + The type of location approximation. Always `approximate`. - The type of the shell call output. Always `shell_call_output`. + - `"approximate"` - - `"shell_call_output"` + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `agent: optional object { agent_name }` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - The agent that produced this item. + - `server_label: string` - - `agent_name: string` + A label for this MCP server, used to identify it in tool calls. - The canonical name of the agent that produced this item. + - `type: "mcp"` - - `caller: optional object { type } or object { caller_id, type }` + The type of the MCP tool. Always `mcp`. - The execution context that produced this tool call. + - `"mcp"` - - `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` + - `"programmatic"` - The call ID of the program item that produced this tool call. + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `type: "program"` + List of allowed tool names or a filter object. - - `"program"` + - `McpAllowedTools = array of string` - - `created_by: optional string` + A string array of allowed tool names - The identifier of the actor that created the item. + - `McpToolFilter object { read_only, tool_names }` - - `ApplyPatchCall object { id, call_id, operation, 5 more }` + A filter object to specify which tools are allowed. - A tool call that applies file diffs by creating, deleting, or updating files. + - `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 apply patch tool call. Populated when this item is returned via API. + - `tool_names: optional array of string` - - `call_id: string` + List of allowed tool names. - The unique ID of the apply patch tool call generated by the model. + - `authorization: optional string` - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, 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. - One of the create_file, delete_file, or update_file operations applied via apply_patch. + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `CreateFile 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). - Instruction describing how to create a file via the apply_patch tool. + Currently supported `connector_id` values are: - - `diff: 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` - Diff to apply. + - `"connector_dropbox"` - - `path: string` + - `"connector_gmail"` - Path of the file to create. + - `"connector_googlecalendar"` - - `type: "create_file"` + - `"connector_googledrive"` - Create a new file with the provided diff. + - `"connector_microsoftteams"` - - `"create_file"` + - `"connector_outlookcalendar"` - - `DeleteFile object { path, type }` + - `"connector_outlookemail"` - Instruction describing how to delete a file via the apply_patch tool. + - `"connector_sharepoint"` - - `path: string` + - `defer_loading: optional boolean` - Path of the file to delete. + Whether this MCP tool is deferred and discovered via tool search. - - `type: "delete_file"` + - `headers: optional map[string]` - Delete the specified file. + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `"delete_file"` + - `require_approval: optional object { always, never } or "always" or "never"` - - `UpdateFile object { diff, path, type }` + Specify which of the MCP server's tools require approval. - Instruction describing how to update a 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. - Diff to apply. + - `always: optional object { read_only, tool_names }` - - `path: string` + A filter object to specify which tools are allowed. - Path of the file to update. + - `read_only: optional boolean` - - `type: "update_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. - Update an existing file with the provided diff. + - `tool_names: optional array of string` - - `"update_file"` + List of allowed tool names. - - `status: "in_progress" or "completed"` + - `never: optional object { read_only, tool_names }` - The status of the apply patch tool call. One of `in_progress` or `completed`. + 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. - - `type: "apply_patch_call"` + - `tool_names: optional array of string` - The type of the item. Always `apply_patch_call`. + List of allowed tool names. - - `"apply_patch_call"` + - `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` - - `"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. - - `Program object { caller_id, type }` + - `CodeInterpreter object { container, type, allowed_callers }` - - `caller_id: string` + A tool that runs Python code to help generate a response to a prompt. - The call ID of the program item that produced this tool call. + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `type: "program"` + 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. - - `"program"` + - `string` - - `created_by: optional string` + The container ID. - The ID of the entity that created this tool call. + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - - `ApplyPatchCallOutput object { id, call_id, status, 5 more }` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - The output emitted by an apply patch tool call. + - `type: "auto"` - - `id: string` + Always `auto`. - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `"auto"` - - `call_id: string` + - `file_ids: optional array of string` - The unique ID of the apply patch tool call generated by the model. + An optional list of uploaded files to make available to your code. - - `status: "completed" or "failed"` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - The status of the apply patch tool call output. One of `completed` or `failed`. + The memory limit for the code interpreter container. - - `"completed"` + - `"1g"` - - `"failed"` + - `"4g"` - - `type: "apply_patch_call_output"` + - `"16g"` - The type of the item. Always `apply_patch_call_output`. + - `"64g"` - - `"apply_patch_call_output"` + - `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 }` - - - `caller_id: string` - - The call ID of the program item that produced this tool call. + - `"programmatic"` - - `type: "program"` + - `ProgrammaticToolCalling object { type }` - - `"program"` + - `type: "programmatic_tool_calling"` - - `created_by: optional string` + The type of the tool. Always `programmatic_tool_calling`. - The ID of the entity that created this tool call output. + - `"programmatic_tool_calling"` - - `output: optional string` + - `ImageGeneration object { type, action, background, 9 more }` - Optional textual output returned by the apply patch tool. + A tool that generates images using the GPT image models. - - `McpCall object { id, arguments, name, 7 more }` + - `type: "image_generation"` - An invocation of a tool on an MCP server. + The type of the image generation tool. Always `image_generation`. - - `id: string` + - `"image_generation"` - The unique ID of the tool call. + - `action: optional "generate" or "edit" or "auto"` - - `arguments: string` + Whether to generate a new image or edit an existing image. Default: `auto`. - A JSON string of the arguments passed to the tool. + - `"generate"` - - `name: string` + - `"edit"` - The name of the tool that was run. + - `"auto"` - - `server_label: string` + - `background: optional "transparent" or "opaque" or "auto"` - The label of the MCP server running the tool. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - - `type: "mcp_call"` + - `"transparent"` - The type of the item. Always `mcp_call`. + - `"opaque"` - - `"mcp_call"` + - `"auto"` - - `agent: optional object { agent_name }` + - `input_fidelity: optional "high" or "low"` - 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`. - - `agent_name: string` + - `"high"` - The canonical name of the agent that produced this item. + - `"low"` - - `approval_request_id: optional string` + - `input_image_mask: optional object { file_id, image_url }` - 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. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `error: optional string` + - `file_id: optional string` - The error from the tool call, if any. + File ID for the mask image. - - `output: optional string` + - `image_url: optional string` - The output from the tool call. + Base64-encoded mask image. - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `model: optional string or "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"` + - `string` - - `"completed"` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `"incomplete"` + The image generation model to use. Default: `gpt-image-1`. - - `"calling"` + - `"gpt-image-1"` - - `"failed"` + - `"gpt-image-1-mini"` - - `McpListTools object { id, server_label, tools, 3 more }` + - `"gpt-image-1.5"` - A list of tools available on an MCP server. + - `moderation: optional "auto" or "low"` - - `id: string` + Moderation level for the generated image. Default: `auto`. - The unique ID of the list. + - `"auto"` - - `server_label: string` + - `"low"` - The label of the MCP server. + - `output_compression: optional number` - - `tools: array of object { input_schema, name, annotations, description }` + Compression level for the output image. Default: 100. - The tools available on the server. + - `output_format: optional "png" or "webp" or "jpeg"` - - `input_schema: unknown` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - The JSON schema describing the tool's input. + - `"png"` - - `name: string` + - `"webp"` - The name of the tool. + - `"jpeg"` - - `annotations: optional unknown` + - `partial_images: optional number` - Additional annotations about the tool. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `description: optional string` + - `quality: optional "low" or "medium" or "high" or "auto"` - The description of the tool. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `type: "mcp_list_tools"` + - `"low"` - The type of the item. Always `mcp_list_tools`. + - `"medium"` - - `"mcp_list_tools"` + - `"high"` - - `agent: optional object { agent_name }` + - `"auto"` - The agent that produced this item. + - `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` - - `error: optional string` + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - Error message if the server could not 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`. - - `McpApprovalRequest object { id, arguments, name, 3 more }` + - `"1024x1024"` - A request for human approval of a tool invocation. + - `"1024x1536"` - - `id: string` + - `"1536x1024"` - The unique ID of the approval request. + - `"auto"` - - `arguments: string` + - `LocalShell object { type }` - A JSON string of arguments for the tool. + A tool that allows the model to execute shell commands in a local environment. - - `name: string` + - `type: "local_shell"` - The name of the tool to run. + The type of the local shell tool. Always `local_shell`. - - `server_label: string` + - `"local_shell"` - The label of the MCP server making the request. + - `Shell object { type, allowed_callers, environment }` - - `type: "mcp_approval_request"` + A tool that allows the model to execute shell commands. - The type of the item. Always `mcp_approval_request`. + - `type: "shell"` - - `"mcp_approval_request"` + The type of the shell tool. Always `shell`. - - `agent: optional object { agent_name }` + - `"shell"` - 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"` - - `McpApprovalResponse object { id, approval_request_id, approve, 3 more }` + - `"programmatic"` - A response to an MCP approval request. + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - `id: string` + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - The unique ID of the approval response + - `BetaLocalEnvironment object { type, skills }` - - `approval_request_id: string` + - `BetaContainerReference object { container_id, type }` - The ID of the approval request being answered. + - `Custom object { name, type, allowed_callers, 3 more }` - - `approve: boolean` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - Whether the request was approved. + - `name: string` - - `type: "mcp_approval_response"` + The name of the custom tool, used to identify it in tool calls. - The type of the item. Always `mcp_approval_response`. + - `type: "custom"` - - `"mcp_approval_response"` + 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"` - - `reason: optional string` + - `"programmatic"` - Optional reason for the decision. + - `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"` + - `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` - - `"program"` + The namespace name used in tool calls (for example, `crm`). - - `namespace: optional string` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - The namespace of the custom tool being called. + The function/custom tools available inside this namespace. - - `CustomToolCallOutput object { id, call_id, output, 5 more }` + - `Function object { name, type, allowed_callers, 5 more }` - - `id: string` + - `name: string` - The unique ID of the custom tool call output item. + - `type: "function"` - - `call_id: string` + - `"function"` - The call ID, used to map this custom tool call output to a custom tool call. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + The tool invocation context(s). - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `"direct"` - - `StringOutput = string` + - `"programmatic"` - A string of the output of the custom tool call. + - `defer_loading: optional boolean` - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + Whether this function should be deferred and discovered via tool search. - Text, image, or file output of the custom tool call. + - `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](https://platform.openai.com/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 }` - - `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: "custom_tool_call_output"` + - `"custom"` - The type of the custom tool call output. Always `custom_tool_call_output`. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"custom_tool_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"` - - `parallel_tool_calls: boolean` + The syntax of the grammar definition. One of `lark` or `regex`. - Whether to allow the model to run tool calls in parallel. + - `"lark"` - - `temperature: number` + - `"regex"` - 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: "grammar"` - - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` + Grammar format. Always `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. + - `"grammar"` - - `BetaToolChoiceOptions = "none" or "auto" or "required"` + - `type: "namespace"` - Controls which (if any) tool is called by the model. + The type of the tool. Always `namespace`. - `none` means the model will not call any tool and instead generates a message. + - `"namespace"` - `auto` means the model can pick between generating a message or calling one or - more tools. + - `ToolSearch object { type, description, execution, parameters }` - `required` means the model must call one or more tools. + Hosted or BYOT tool search configuration for deferred tools. - - `"none"` + - `type: "tool_search"` - - `"auto"` + The type of the tool. Always `tool_search`. - - `"required"` + - `"tool_search"` - - `BetaToolChoiceAllowed object { mode, tools, type }` + - `description: optional string` - Constrains the tools available to the model to a pre-defined set. + Description shown to the model for a client-executed tool search tool. - - `mode: "auto" or "required"` + - `execution: optional "server" or "client"` - Constrains the tools available to the model to a pre-defined set. + Whether tool search is executed by the server or by the client. - `auto` allows the model to pick from among the allowed tools and generate a - message. + - `"server"` - `required` requires the model to call one or more of the allowed tools. + - `"client"` - - `"auto"` + - `parameters: optional unknown` - - `"required"` + Parameter schema for a client-executed tool search tool. - - `tools: array of map[unknown]` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - A list of tool definitions that the model should be allowed to 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). - For the Responses API, the list of tool definitions might look like: + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `type: "allowed_tools"` + - `"web_search_preview"` - Allowed tool configuration type. Always `allowed_tools`. + - `"web_search_preview_2025_03_11"` - - `"allowed_tools"` + - `search_content_types: optional array of "text" or "image"` - - `BetaToolChoiceTypes object { type }` + - `"text"` - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + - `"image"` - - `type: "file_search" or "web_search_preview" or "computer" or 5 more` + - `search_context_size: optional "low" or "medium" or "high"` - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + 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. - Allowed values are: + - `"low"` - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + - `"medium"` - - `"file_search"` + - `"high"` - - `"web_search_preview"` + - `user_location: optional object { type, city, country, 2 more }` - - `"computer"` + The user's location. - - `"computer_use_preview"` + - `type: "approximate"` - - `"computer_use"` + The type of location approximation. Always `approximate`. - - `"web_search_preview_2025_03_11"` + - `"approximate"` - - `"image_generation"` + - `city: optional string` - - `"code_interpreter"` + Free text input for the city of the user, e.g. `San Francisco`. - - `BetaToolChoiceFunction object { name, type }` + - `country: optional string` - Use this option to force the model to call a specific function. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `name: string` + - `region: optional string` - The name of the function to call. + Free text input for the region of the user, e.g. `California`. - - `type: "function"` + - `timezone: optional string` - For function calling, the type is always `function`. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `"function"` + - `ApplyPatch object { type, allowed_callers }` - - `BetaToolChoiceMcp object { server_label, type, name }` + Allows the assistant to create, delete, or update files using unified diffs. - Use this option to force the model to call a specific tool on a remote MCP server. + - `type: "apply_patch"` - - `server_label: string` + The type of the tool. Always `apply_patch`. - The label of the MCP server to use. + - `"apply_patch"` - - `type: "mcp"` + - `allowed_callers: optional array of "direct" or "programmatic"` - For MCP tools, the type is always `mcp`. + The tool invocation context(s). - - `"mcp"` + - `"direct"` - - `name: optional string` + - `"programmatic"` - The name of the tool to call on the server. + - `type: "tool_search_output"` - - `BetaToolChoiceCustom object { name, type }` + The type of the item. Always `tool_search_output`. - Use this option to force the model to call a specific custom tool. + - `"tool_search_output"` - - `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"` + - `created_by: optional string` - - `BetaSpecificProgrammaticToolCallingParam object { type }` + The identifier of the actor that created the item. - - `type: "programmatic_tool_calling"` + - `AdditionalTools object { id, role, tools, 2 more }` - The tool to call. Always `programmatic_tool_calling`. + - `id: string` - - `"programmatic_tool_calling"` + The unique ID of the additional tools item. - - `BetaToolChoiceApplyPatch object { type }` + - `role: "unknown" or "user" or "assistant" or 5 more` - Forces the model to call the apply_patch tool when executing a tool call. + The role that provided the additional tools. - - `type: "apply_patch"` + - `"unknown"` - The tool to call. Always `apply_patch`. + - `"user"` - - `"apply_patch"` + - `"assistant"` - - `BetaToolChoiceShell object { type }` + - `"system"` - Forces the model to call the shell tool when a tool call is required. + - `"critic"` - - `type: "shell"` + - `"discriminator"` - The tool to call. Always `shell`. + - `"developer"` - - `"shell"` + - `"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` - 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](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/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](https://platform.openai.com/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](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. + The additional tool definitions made available at this item. - `Function object { name, parameters, strict, 5 more }` @@ -109547,7 +107983,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-web-search). + [web search tool](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -109607,7 +108043,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -109659,7 +108095,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -109851,19 +108287,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `background: optional "transparent" or "opaque" or "auto"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. - - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. - - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - `"transparent"` @@ -109892,13 +108317,13 @@ curl -X POST https://api.openai.com/v1/responses/compact \ Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `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-2" or 3 more` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` The image generation model to use. Default: `gpt-image-1`. @@ -109906,14 +108331,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"gpt-image-1-mini"` - - `"gpt-image-2"` - - - `"gpt-image-2-2026-04-21"` - - `"gpt-image-1.5"` - - `"chatgpt-image-latest"` - - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -110010,7 +108429,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -110124,7 +108543,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -110292,984 +108711,747 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"programmatic"` - - `top_p: number` + - `type: "additional_tools"` - An alternative to sampling with temperature, called nucleus sampling, - where the model considers the results of the tokens with top_p probability - mass. So 0.1 means only the tokens comprising the top 10% probability mass - are considered. + The type of the item. Always `additional_tools`. - We generally recommend altering this or `temperature` but not both. + - `"additional_tools"` - - `background: optional boolean` + - `agent: optional object { agent_name }` - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + The agent that produced this item. - - `completed_at: optional number` + - `agent_name: string` - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + The canonical name of the agent that produced this item. - - `conversation: optional object { id }` + - `Compaction object { id, encrypted_content, type, 2 more }` - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). - `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](https://platform.openai.com/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"` + The unique ID of the compaction item. - - `Error object { code, message, type }` + - `encrypted_content: string` - An error produced while attempting moderation for the response input or output. + The encrypted content that was produced by compaction. - - `code: string` + - `type: "compaction"` - The error code. + The type of the item. Always `compaction`. - - `message: string` + - `"compaction"` - The error message. + - `agent: optional object { agent_name }` - - `type: "error"` + The agent that produced this item. - The object type, which was always `error` for moderation failures. + - `agent_name: string` - - `"error"` + The canonical name of the agent that produced this item. - - `previous_response_id: optional string` + - `created_by: optional string` - The unique ID of the previous response to the model. Use this to - create multi-turn conversations. Learn more about - [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + The identifier of the actor that created the item. - - `prompt: optional BetaResponsePrompt` + - `ImageGenerationCall object { id, result, status, 2 more }` - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + An image generation request made by the model. - `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 }` + The unique ID of the image generation call. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `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"` - - `version: optional string` + The status of the image generation call. - Optional version of the prompt template. + - `"in_progress"` - - `prompt_cache_key: optional string` + - `"completed"` - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + - `"generating"` - - `prompt_cache_options: optional object { mode, ttl }` + - `"failed"` - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + - `type: "image_generation_call"` - - `mode: "implicit" or "explicit"` + The type of the image generation call. Always `image_generation_call`. - Whether implicit prompt-cache breakpoints were enabled. + - `"image_generation_call"` - - `"implicit"` + - `agent: optional object { agent_name }` - - `"explicit"` + The agent that produced this item. - - `ttl: "30m"` + - `agent_name: string` - The minimum lifetime applied to each cache breakpoint. + The canonical name of the agent that produced this item. - - `"30m"` + - `CodeInterpreterCall object { id, code, container_id, 4 more }` - - `prompt_cache_retention: optional "in_memory" or "24h"` + A tool call to run code. - Deprecated. Use `prompt_cache_options.ttl` instead. + - `id: 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](https://platform.openai.com/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 unique ID of the code interpreter tool call. - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + - `code: string` - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + The code to run, or null if not available. - - `"in_memory"` + - `container_id: string` - - `"24h"` + The ID of the container used to run the code. - - `reasoning: optional object { context, effort, generate_summary, 2 more }` + - `outputs: array of object { logs, type } or object { type, url }` - **gpt-5 and o-series models only** + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + - `Logs object { logs, type }` - - `context: optional "auto" or "current_turn" or "all_turns"` + The logs output from the code interpreter. - Controls which reasoning items are rendered back to the model on later turns. - When returned on a response, this is the effective reasoning context mode - used for the response. + - `logs: string` - - `"auto"` + The logs output from the code interpreter. - - `"current_turn"` + - `type: "logs"` - - `"all_turns"` + The type of the output. Always `logs`. - - `effort: optional "none" or "minimal" or "low" or 4 more` + - `"logs"` - 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. + - `Image object { type, url }` - - `"none"` + The image output from the code interpreter. - - `"minimal"` + - `type: "image"` - - `"low"` + The type of the output. Always `image`. - - `"medium"` + - `"image"` - - `"high"` + - `url: string` - - `"xhigh"` + The URL of the image output from the code interpreter. - - `"max"` + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - - `generate_summary: optional "auto" or "concise" or "detailed"` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - **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"` + - `"interpreting"` - - `"detailed"` + - `"failed"` - - `mode: optional string or "standard" or "pro"` + - `type: "code_interpreter_call"` - Controls the reasoning execution mode for the request. + The type of the code interpreter tool call. Always `code_interpreter_call`. - When returned on a response, this is the effective execution mode. + - `"code_interpreter_call"` - - `string` + - `agent: optional object { agent_name }` - - `"standard" or "pro"` + The agent that produced this item. - Controls the reasoning execution mode for the request. + - `agent_name: string` - When returned on a response, this is the effective execution mode. + The canonical name of the agent that produced this item. - - `"standard"` + - `LocalShellCall object { id, action, call_id, 3 more }` - - `"pro"` + A tool call to run a command on the local shell. - - `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 local shell call. - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + - `action: object { command, env, type, 3 more }` - - `"auto"` + Execute a shell command on the server. - - `"concise"` + - `command: array of string` - - `"detailed"` + The command to run. - - `safety_identifier: optional string` + - `env: map[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](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + Environment variables to set for the command. - - `service_tier: optional "auto" or "default" or "flex" or 2 more` + - `type: "exec"` - Specifies the processing type used for serving the request. + The type of the local shell action. Always `exec`. - - 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](https://platform.openai.com/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'. + - `"exec"` - 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. + - `timeout_ms: optional number` - - `"auto"` + Optional timeout in milliseconds for the command. - - `"default"` + - `user: optional string` - - `"flex"` + Optional user to run the command as. - - `"scale"` + - `working_directory: optional string` - - `"priority"` + Optional working directory to run the command in. - - `status: optional BetaResponseStatus` + - `call_id: string` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + The unique ID of the local shell tool call generated by the model. - - `"completed"` + - `status: "in_progress" or "completed" or "incomplete"` - - `"failed"` + The status of the local shell call. - `"in_progress"` - - `"cancelled"` - - - `"queued"` + - `"completed"` - `"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](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/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](https://platform.openai.com/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: "local_shell_call"` - - `type: "text"` + The type of the local shell call. Always `local_shell_call`. - The type of response format being defined. Always `text`. + - `"local_shell_call"` - - `"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](https://platform.openai.com/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. + - `LocalShellCallOutput object { id, output, type, 2 more }` - - `schema: map[unknown]` + The output of a local shell 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/). + - `id: string` - - `type: "json_schema"` + The unique ID of the local shell tool call generated by the model. - The type of response format being defined. Always `json_schema`. + - `output: string` - - `"json_schema"` + A JSON string of the output of the local shell tool call. - - `description: optional string` + - `type: "local_shell_call_output"` - 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 local shell tool call output. Always `local_shell_call_output`. - - `strict: optional boolean` + - `"local_shell_call_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](https://platform.openai.com/docs/guides/structured-outputs). + - `agent: optional object { agent_name }` - - `JSONObject object { type }` + The agent that produced this item. - 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_name: string` - - `type: "json_object"` + The canonical name of the agent that produced this item. - The type of response format being defined. Always `json_object`. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"json_object"` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `verbosity: optional "low" or "medium" or "high"` + - `"in_progress"` - 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`. + - `"completed"` - - `"low"` + - `"incomplete"` - - `"medium"` + - `ShellCall object { id, action, call_id, 6 more }` - - `"high"` + A tool call that executes one or more shell commands in a managed environment. - - `top_logprobs: optional number` + - `id: 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 unique ID of the shell tool call. Populated when this item is returned via API. - - `truncation: optional "auto" or "disabled"` + - `action: object { commands, max_output_length, timeout_ms }` - The truncation strategy to use for the model response. + The shell commands and limits that describe how to run the tool call. - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + - `commands: array of string` - - `"auto"` + - `max_output_length: number` - - `"disabled"` + Optional maximum number of characters to return from each command. - - `usage: optional BetaResponseUsage` + - `timeout_ms: number` - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + Optional timeout in milliseconds for the commands. - - `input_tokens: number` + - `call_id: string` - The number of input tokens. + The unique ID of the shell tool call generated by the model. - - `input_tokens_details: object { cache_write_tokens, cached_tokens }` + - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` - A detailed breakdown of the input tokens. + Represents the use of a local environment to perform shell actions. - - `cache_write_tokens: number` + - `BetaResponseLocalEnvironment object { type }` - The number of input tokens that were written to the cache. + Represents the use of a local environment to perform shell actions. - - `cached_tokens: number` + - `type: "local"` - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + The environment type. Always `local`. - - `output_tokens: number` + - `"local"` - The number of output tokens. + - `BetaResponseContainerReference object { container_id, type }` - - `output_tokens_details: object { reasoning_tokens }` + Represents a container created with /v1/containers. - A detailed breakdown of the output tokens. + - `container_id: string` - - `reasoning_tokens: number` + - `type: "container_reference"` - The number of reasoning tokens. + The environment type. Always `container_reference`. - - `total_tokens: number` + - `"container_reference"` - The total number of tokens used. + - `status: "in_progress" or "completed" or "incomplete"` - - `user: optional string` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - 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](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `"in_progress"` - - `sequence_number: number` + - `"completed"` - The sequence number for this event. + - `"incomplete"` - - `type: "response.created"` + - `type: "shell_call"` - The type of the event. Always `response.created`. + The type of the item. Always `shell_call`. - - `"response.created"` + - `"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. -### Beta Response Custom Tool Call Input Delta Event - -- `BetaResponseCustomToolCallInputDeltaEvent object { delta, item_id, output_index, 3 more }` - - Event representing a delta (partial update) to the input of a custom tool call. - - - `delta: string` - - The incremental input data (delta) for the custom tool call. - - - `item_id: string` - - Unique identifier for the API item associated with this event. - - - `output_index: number` - - The index of the output this delta applies to. - - - `sequence_number: number` - - The sequence number of this event. + - `caller: optional object { type } or object { caller_id, type }` - - `type: "response.custom_tool_call_input.delta"` + The execution context that produced this tool call. - The event type identifier. + - `Direct object { type }` - - `"response.custom_tool_call_input.delta"` + - `type: "direct"` - - `agent: optional object { agent_name }` + - `"direct"` - The agent that owns this multi-agent streaming event. + - `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. -### Beta Response Custom Tool Call Input Done Event + - `type: "program"` -- `BetaResponseCustomToolCallInputDoneEvent object { input, item_id, output_index, 3 more }` + - `"program"` - Event indicating that input for a custom tool call is complete. + - `created_by: optional string` - - `input: string` + The ID of the entity that created this tool call. - The complete input data for the custom tool call. + - `ShellCallOutput object { id, call_id, max_output_length, 6 more }` - - `item_id: string` + The output of a shell tool call that was emitted. - Unique identifier for the API item associated with this event. + - `id: string` - - `output_index: number` + The unique ID of the shell call output. Populated when this item is returned via API. - The index of the output this event applies to. + - `call_id: string` - - `sequence_number: number` + The unique ID of the shell tool call generated by the model. - The sequence number of this event. + - `max_output_length: number` - - `type: "response.custom_tool_call_input.done"` + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - The event type identifier. + - `output: array of object { outcome, stderr, stdout, created_by }` - - `"response.custom_tool_call_input.done"` + An array of shell call output contents - - `agent: optional object { agent_name }` + - `outcome: object { type } or object { exit_code, type }` - The agent that owns this multi-agent streaming event. + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - - `agent_name: string` + - `Timeout object { type }` - The canonical name of the agent that produced this item. + Indicates that the shell call exceeded its configured time limit. -### Beta Response Error + - `type: "timeout"` -- `BetaResponseError object { code, message }` + The outcome type. Always `timeout`. - An error object returned when the model fails to generate a Response. + - `"timeout"` - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 16 more` + - `Exit object { exit_code, type }` - The error code for the response. + Indicates that the shell commands finished and returned an exit code. - - `"server_error"` + - `exit_code: number` - - `"rate_limit_exceeded"` + Exit code from the shell process. - - `"invalid_prompt"` + - `type: "exit"` - - `"bio_policy"` + The outcome type. Always `exit`. - - `"vector_store_timeout"` + - `"exit"` - - `"invalid_image"` + - `stderr: string` - - `"invalid_image_format"` + The standard error output that was captured. - - `"invalid_base64_image"` + - `stdout: string` - - `"invalid_image_url"` + The standard output that was captured. - - `"image_too_large"` + - `created_by: optional string` - - `"image_too_small"` + The identifier of the actor that created the item. - - `"image_parse_error"` + - `status: "in_progress" or "completed" or "incomplete"` - - `"image_content_policy_violation"` + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - `"invalid_image_mode"` + - `"in_progress"` - - `"image_file_too_large"` + - `"completed"` - - `"unsupported_image_media_type"` + - `"incomplete"` - - `"empty_image_file"` + - `type: "shell_call_output"` - - `"failed_to_download_image"` + The type of the shell call output. Always `shell_call_output`. - - `"image_file_not_found"` + - `"shell_call_output"` - - `message: string` + - `agent: optional object { agent_name }` - A human-readable description of the error. + The agent that produced this item. -### Beta Response Error Event + - `agent_name: string` -- `BetaResponseErrorEvent object { code, message, param, 3 more }` + The canonical name of the agent that produced this item. - Emitted when an error occurs. + - `caller: optional object { type } or object { caller_id, type }` - - `code: string` + The execution context that produced this tool call. - The error code. + - `Direct object { type }` - - `message: string` + - `type: "direct"` - The error message. + - `"direct"` - - `param: string` + - `Program object { caller_id, type }` - The error parameter. + - `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: "error"` + - `"program"` - The type of the event. Always `error`. + - `created_by: optional string` - - `"error"` + The identifier of the actor that created the item. - - `agent: optional object { agent_name }` + - `ApplyPatchCall object { id, call_id, operation, 5 more }` - The agent that owns this multi-agent streaming event. + A tool call that applies file diffs by creating, deleting, or updating files. - - `agent_name: string` + - `id: string` - The canonical name of the agent that produced this item. + The unique ID of the apply patch tool call. Populated when this item is returned via API. -### Beta Response Failed Event + - `call_id: string` -- `BetaResponseFailedEvent object { response, sequence_number, type, agent }` + The unique ID of the apply patch tool call generated by the model. - An event that is emitted when a response fails. + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - - `response: BetaResponse` + One of the create_file, delete_file, or update_file operations applied via apply_patch. - The response that failed. + - `CreateFile object { diff, path, type }` - - `id: string` + Instruction describing how to create a file via the apply_patch tool. - Unique identifier for this Response. + - `diff: string` - - `created_at: number` + Diff to apply. - Unix timestamp (in seconds) of when this Response was created. + - `path: string` - - `error: BetaResponseError` + Path of the file to create. - An error object returned when the model fails to generate a Response. + - `type: "create_file"` - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 16 more` + Create a new file with the provided diff. - The error code for the response. + - `"create_file"` - - `"server_error"` + - `DeleteFile object { path, type }` - - `"rate_limit_exceeded"` + Instruction describing how to delete a file via the apply_patch tool. - - `"invalid_prompt"` + - `path: string` - - `"bio_policy"` + Path of the file to delete. - - `"vector_store_timeout"` + - `type: "delete_file"` - - `"invalid_image"` + Delete the specified file. - - `"invalid_image_format"` + - `"delete_file"` - - `"invalid_base64_image"` + - `UpdateFile object { diff, path, type }` - - `"invalid_image_url"` + Instruction describing how to update a file via the apply_patch tool. - - `"image_too_large"` + - `diff: string` - - `"image_too_small"` + Diff to apply. - - `"image_parse_error"` + - `path: string` - - `"image_content_policy_violation"` + Path of the file to update. - - `"invalid_image_mode"` + - `type: "update_file"` - - `"image_file_too_large"` + Update an existing file with the provided diff. - - `"unsupported_image_media_type"` + - `"update_file"` - - `"empty_image_file"` + - `status: "in_progress" or "completed"` - - `"failed_to_download_image"` + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `"image_file_not_found"` + - `"in_progress"` - - `message: string` + - `"completed"` - A human-readable description of the error. + - `type: "apply_patch_call"` - - `incomplete_details: object { reason }` + The type of the item. Always `apply_patch_call`. - Details about why the response is incomplete. + - `"apply_patch_call"` - - `reason: optional "max_output_tokens" or "content_filter"` + - `agent: optional object { agent_name }` - The reason why the response is incomplete. + The agent that produced this item. - - `"max_output_tokens"` + - `agent_name: string` - - `"content_filter"` + The canonical name of the agent that produced this item. - - `instructions: string or array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + - `caller: optional object { type } or object { caller_id, type }` - A system (or developer) message inserted into the model's context. + The execution context that produced this tool 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. + - `Direct object { type }` - - `string` + - `type: "direct"` - A text input to the model, equivalent to a text input with the - `developer` role. + - `"direct"` - - `InputItemList = array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + - `Program object { caller_id, type }` - A list of one or many input items to the model, containing - different content types. + - `caller_id: string` - - `BetaEasyInputMessage object { content, role, phase, type }` + The call ID of the program item that produced this tool call. - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. Messages with the - `assistant` role are presumed to have been generated by the model in previous - interactions. + - `type: "program"` - - `content: string or BetaResponseInputMessageContentList` + - `"program"` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + - `created_by: optional string` - - `TextInput = string` + The ID of the entity that created this tool call. - A text input to the model. + - `ApplyPatchCallOutput object { id, call_id, status, 5 more }` - - `BetaResponseInputMessageContentList = array of BetaResponseInputContent` + The output emitted by an apply patch tool call. - A list of one or many input items to the model, containing different content - types. + - `id: string` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - A text input to the model. + - `call_id: string` - - `text: string` + The unique ID of the apply patch tool call generated by the model. - The text input to the model. + - `status: "completed" or "failed"` - - `type: "input_text"` + The status of the apply patch tool call output. One of `completed` or `failed`. - The type of the input item. Always `input_text`. + - `"completed"` - - `"input_text"` + - `"failed"` - - `prompt_cache_breakpoint: optional object { mode }` + - `type: "apply_patch_call_output"` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The type of the item. Always `apply_patch_call_output`. - - `mode: "explicit"` + - `"apply_patch_call_output"` - The breakpoint mode. Always `explicit`. + - `agent: optional object { agent_name }` - - `"explicit"` + The agent that produced this item. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `agent_name: string` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The canonical name of the agent that produced this item. - - `detail: "low" or "high" or "auto" or "original"` + - `caller: optional object { type } or 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`. + The execution context that produced this tool call. - - `"low"` + - `Direct object { type }` - - `"high"` + - `type: "direct"` - - `"auto"` + - `"direct"` - - `"original"` + - `Program object { caller_id, type }` - - `type: "input_image"` + - `caller_id: string` - The type of the input item. Always `input_image`. + The call ID of the program item that produced this tool call. - - `"input_image"` + - `type: "program"` - - `file_id: optional string` + - `"program"` - The ID of the file to be sent to the model. + - `created_by: optional string` - - `image_url: optional string` + The ID of the entity that created this tool 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. + - `output: optional string` - - `prompt_cache_breakpoint: optional object { mode }` + Optional textual output returned by the apply patch 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. + - `McpCall object { id, arguments, name, 7 more }` - - `mode: "explicit"` + An invocation of a tool on an MCP server. - The breakpoint mode. Always `explicit`. + - `id: string` - - `"explicit"` + The unique ID of the tool call. - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `arguments: string` - A file input to the model. + A JSON string of the arguments passed to the tool. - - `type: "input_file"` + - `name: string` - The type of the input item. Always `input_file`. + The name of the tool that was run. - - `"input_file"` + - `server_label: string` - - `detail: optional "auto" or "low" or "high"` + The label of the MCP server running the 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`. + - `type: "mcp_call"` - - `"auto"` + The type of the item. Always `mcp_call`. - - `"low"` + - `"mcp_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. + - `approval_request_id: optional string` - - `file_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 file to be sent to the model. + - `error: optional string` - - `filename: optional string` + The error from the tool call, if any. - The name of the file to be sent to the model. + - `output: optional string` - - `prompt_cache_breakpoint: optional object { mode }` + The output from the 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. + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - - `mode: "explicit"` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - The breakpoint mode. Always `explicit`. + - `"in_progress"` - - `"explicit"` + - `"completed"` - - `role: "user" or "assistant" or "system" or "developer"` + - `"incomplete"` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + - `"calling"` - - `"user"` + - `"failed"` - - `"assistant"` + - `McpListTools object { id, server_label, tools, 3 more }` - - `"system"` + A list of tools available on an MCP server. - - `"developer"` + - `id: string` - - `phase: optional "commentary" or "final_answer"` + The unique ID of the list. - 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"` + The label of the MCP server. - - `"final_answer"` + - `tools: array of object { input_schema, name, annotations, description }` - - `type: optional "message"` + The tools available on the server. - The type of the message input. Always `message`. + - `input_schema: unknown` - - `"message"` + The JSON schema describing the tool's input. - - `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. - - `content: BetaResponseInputMessageContentList` + - `annotations: optional unknown` - A list of one or many input items to the model, containing different content - types. + Additional annotations about the tool. - - `role: "user" or "system" or "developer"` + - `description: optional string` - The role of the message input. One of `user`, `system`, or `developer`. + The description of the tool. - - `"user"` + - `type: "mcp_list_tools"` - - `"system"` + The type of the item. Always `mcp_list_tools`. - - `"developer"` + - `"mcp_list_tools"` - `agent: optional object { agent_name }` @@ -111279,189 +109461,175 @@ 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"` - - The type of the message input. Always set to `message`. + - `error: optional string` - - `"message"` + Error message if the server could not list tools. - - `BetaResponseOutputMessage object { id, content, role, 4 more }` + - `McpApprovalRequest object { id, arguments, name, 3 more }` - An output message from the model. + A request for human approval of a tool invocation. - `id: string` - The unique ID of the output message. - - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + The unique ID of the approval request. - The content of the output message. + - `arguments: string` - - `BetaResponseOutputText object { annotations, text, type, logprobs }` + A JSON string of arguments for the tool. - A text output from the model. + - `name: 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 name of the tool to run. - The annotations of the text output. + - `server_label: string` - - `FileCitation object { file_id, filename, index, type }` + The label of the MCP server making the request. - A citation to a file. + - `type: "mcp_approval_request"` - - `file_id: string` + The type of the item. Always `mcp_approval_request`. - The ID of the file. + - `"mcp_approval_request"` - - `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"` + - `McpApprovalResponse object { id, approval_request_id, approve, 3 more }` - The type of the file citation. Always `file_citation`. + A response to an MCP approval request. - - `"file_citation"` + - `id: string` - - `URLCitation object { end_index, start_index, title, 2 more }` + The unique ID of the approval response - A citation for a web resource used to generate a model response. + - `approval_request_id: string` - - `end_index: number` + The ID of the approval request being answered. - The index of the last character of the URL citation in the message. + - `approve: boolean` - - `start_index: number` + Whether the request was approved. - The index of the first character of the URL citation in the message. + - `type: "mcp_approval_response"` - - `title: string` + The type of the item. Always `mcp_approval_response`. - The title of the web resource. + - `"mcp_approval_response"` - - `type: "url_citation"` + - `agent: optional object { agent_name }` - The type of the URL citation. 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 web resource. + - `reason: optional string` - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + Optional reason for the decision. - A citation for a container file used to generate a model response. + - `CustomToolCall object { call_id, input, name, 5 more }` - - `container_id: string` + A call to a custom tool created by the model. - The ID of the container file. + - `call_id: string` - - `end_index: number` + An identifier used to map this custom tool call to a tool call output. - The index of the last character of the container file citation in the message. + - `input: string` - - `file_id: string` + The input for the custom tool call generated by the model. - The ID of the file. + - `name: string` - - `filename: string` + The name of the custom tool being called. - The filename of the container file cited. + - `type: "custom_tool_call"` - - `start_index: number` + The type of the custom tool call. Always `custom_tool_call`. - The index of the first character of the container file citation in the message. + - `"custom_tool_call"` - - `type: "container_file_citation"` + - `id: optional string` - The type of the container file citation. Always `container_file_citation`. + The unique ID of the custom tool call in the OpenAI platform. - - `"container_file_citation"` + - `agent: optional object { agent_name }` - - `FilePath object { file_id, index, type }` + The agent that produced this item. - A path to a file. + - `agent_name: string` - - `file_id: string` + The canonical name of the agent that produced this item. - The ID of the file. + - `caller: optional object { type } or object { caller_id, type }` - - `index: number` + The execution context that produced this tool call. - The index of the file in the list of files. + - `Direct object { type }` - - `type: "file_path"` + - `type: "direct"` - The type of the file path. Always `file_path`. + - `"direct"` - - `"file_path"` + - `Program object { caller_id, type }` - - `text: string` + - `caller_id: string` - The text output from the model. + The call ID of the program item that produced this tool call. - - `type: "output_text"` + - `type: "program"` - The type of the output text. Always `output_text`. + - `"program"` - - `"output_text"` + - `namespace: optional string` - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + The namespace of the custom tool being called. - - `token: string` + - `CustomToolCallOutput object { id, call_id, output, 5 more }` - - `bytes: array of number` + - `id: string` - - `logprob: number` + The unique ID of the custom tool call output item. - - `top_logprobs: array of object { token, bytes, logprob }` + - `call_id: string` - - `token: string` + The call ID, used to map this custom tool call output to a custom tool call. - - `bytes: array of number` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `logprob: number` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `BetaResponseOutputRefusal object { refusal, type }` + - `StringOutput = string` - A refusal from the model. + A string of the output of the custom tool call. - - `refusal: string` + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - The refusal explanation from the model. + Text, image, or file output of the custom tool call. - - `type: "refusal"` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - The type of the refusal. Always `refusal`. + A text input to the model. - - `"refusal"` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `role: "assistant"` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - The role of the output message. Always `assistant`. + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `"assistant"` + A file input to the model. - `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. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `"in_progress"` @@ -111469,11 +109637,11 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"incomplete"` - - `type: "message"` + - `type: "custom_tool_call_output"` - The type of the output message. Always `message`. + The type of the custom tool call output. Always `custom_tool_call_output`. - - `"message"` + - `"custom_tool_call_output"` - `agent: optional object { agent_name }` @@ -111483,2256 +109651,2333 @@ 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"` - - - `FileSearchCall object { id, queries, status, 3 more }` - - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/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`, + - `caller: optional object { type } or object { caller_id, type }` - - `"in_progress"` + The execution context that produced this tool call. - - `"searching"` + - `Direct object { type }` - - `"completed"` + - `type: "direct"` - - `"incomplete"` + The caller type. Always `direct`. - - `"failed"` + - `"direct"` - - `type: "file_search_call"` + - `Program object { caller_id, type }` - The type of the file search tool call. Always `file_search_call`. + - `caller_id: string` - - `"file_search_call"` + The call ID of the program item that produced this tool call. - - `agent: optional object { agent_name }` + - `type: "program"` - The agent that produced this item. + The caller type. Always `program`. - - `agent_name: string` + - `"program"` - The canonical name of the agent that produced this item. + - `created_by: optional string` - - `results: optional array of object { attributes, file_id, filename, 2 more }` + The identifier of the actor that created the item. - The results of the file search tool call. + - `parallel_tool_calls: boolean` - - `attributes: optional map[string or number or boolean]` + Whether to allow the model to run tool calls in parallel. - 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. + - `temperature: number` - - `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. - - `number` + - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` - - `boolean` + 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. - - `file_id: optional string` + - `BetaToolChoiceOptions = "none" or "auto" or "required"` - The unique ID of the file. + Controls which (if any) tool is called by the model. - - `filename: optional string` + `none` means the model will not call any tool and instead generates a message. - The name of the file. + `auto` means the model can pick between generating a message or calling one or + more tools. - - `score: optional number` + `required` means the model must call one or more tools. - The relevance score of the file - a value between 0 and 1. + - `"none"` - - `text: optional string` + - `"auto"` - The text that was retrieved from the file. + - `"required"` - - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` + - `BetaToolChoiceAllowed object { mode, tools, type }` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + Constrains the tools available to the model to a pre-defined set. - - `id: string` + - `mode: "auto" or "required"` - The unique ID of the computer call. + Constrains the tools available to the model to a pre-defined set. - - `call_id: string` + `auto` allows the model to pick from among the allowed tools and generate a + message. - An identifier used when responding to the tool call with output. + `required` requires the model to call one or more of the allowed tools. - - `pending_safety_checks: array of object { id, code, message }` + - `"auto"` - The pending safety checks for the computer call. + - `"required"` - - `id: string` + - `tools: array of map[unknown]` - The ID of the pending safety check. + A list of tool definitions that the model should be allowed to call. - - `code: optional string` + For the Responses API, the list of tool definitions might look like: - The type of the pending safety check. + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - - `message: optional string` + - `type: "allowed_tools"` - Details about the pending safety check. + Allowed tool configuration type. Always `allowed_tools`. - - `status: "in_progress" or "completed" or "incomplete"` + - `"allowed_tools"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `BetaToolChoiceTypes object { type }` - - `"in_progress"` + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](/docs/guides/tools). - - `"completed"` + - `type: "file_search" or "web_search_preview" or "computer" or 5 more` - - `"incomplete"` + The type of hosted tool the model should to use. Learn more about + [built-in tools](/docs/guides/tools). - - `type: "computer_call"` + Allowed values are: - The type of the computer call. Always `computer_call`. + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - - `"computer_call"` + - `"file_search"` - - `action: optional BetaComputerAction` + - `"web_search_preview"` - A click action. + - `"computer"` - - `Click object { button, type, x, 2 more }` + - `"computer_use_preview"` - A click action. + - `"computer_use"` - - `button: "left" or "right" or "wheel" or 2 more` + - `"web_search_preview_2025_03_11"` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `"image_generation"` - - `"left"` + - `"code_interpreter"` - - `"right"` + - `BetaToolChoiceFunction object { name, type }` - - `"wheel"` + Use this option to force the model to call a specific function. - - `"back"` + - `name: string` - - `"forward"` + The name of the function to call. - - `type: "click"` + - `type: "function"` - Specifies the event type. For a click action, this property is always `click`. + For function calling, the type is always `function`. - - `"click"` + - `"function"` - - `x: number` + - `BetaToolChoiceMcp object { server_label, type, name }` - The x-coordinate where the click occurred. + Use this option to force the model to call a specific tool on a remote MCP server. - - `y: number` + - `server_label: string` - The y-coordinate where the click occurred. + The label of the MCP server to use. - - `keys: optional array of string` + - `type: "mcp"` - The keys being held while clicking. + For MCP tools, the type is always `mcp`. - - `DoubleClick object { keys, type, x, y }` + - `"mcp"` - A double click action. + - `name: optional string` - - `keys: array of string` + The name of the tool to call on the server. - The keys being held while double-clicking. + - `BetaToolChoiceCustom object { name, type }` - - `type: "double_click"` + Use this option to force the model to call a specific custom tool. - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `name: string` - - `"double_click"` + The name of the custom tool to call. - - `x: number` + - `type: "custom"` - The x-coordinate where the double click occurred. + For custom tool calling, the type is always `custom`. - - `y: number` + - `"custom"` - The y-coordinate where the double click occurred. + - `BetaSpecificProgrammaticToolCallingParam object { type }` - - `Drag object { path, type, keys }` + - `type: "programmatic_tool_calling"` - A drag action. + The tool to call. Always `programmatic_tool_calling`. - - `path: array of object { x, y }` + - `"programmatic_tool_calling"` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `BetaToolChoiceApplyPatch object { type }` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + Forces the model to call the apply_patch tool when executing a tool call. - - `x: number` + - `type: "apply_patch"` - The x-coordinate. + The tool to call. Always `apply_patch`. - - `y: number` + - `"apply_patch"` - The y-coordinate. + - `BetaToolChoiceShell object { type }` - - `type: "drag"` + Forces the model to call the shell tool when a tool call is required. - Specifies the event type. For a drag action, this property is always set to `drag`. + - `type: "shell"` - - `"drag"` + The tool to call. Always `shell`. - - `keys: optional array of string` + - `"shell"` - The keys being held while dragging the mouse. + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - - `Keypress object { keys, 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. - A collection of keypresses the model would like to perform. + We support the following categories of tools: - - `keys: array of 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 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](https://platform.openai.com/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](https://platform.openai.com/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 BetaResponseFunctionCallOutputItemList` + 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` - - `BetaResponseFunctionCallOutputItemList = array of BetaResponseFunctionCallOutputItem` + 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](https://platform.openai.com/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](https://platform.openai.com/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 array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` + - `"text"` - Citations associated with the text content. + - `Grammar object { definition, syntax, type }` - - `array of 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"` - - `array of 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"` - - `array of 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` + - `top_p: number` - - `boolean` + 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. - - `array of string or number` + We generally recommend altering this or `temperature` but not both. - - `string` + - `background: optional boolean` - - `number` + Whether to run the model response in the background. + [Learn more](/docs/guides/background). - - `CompoundFilter object { filters, type }` + - `completed_at: optional number` - Combine multiple filters using `and` or `or`. + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - - `filters: array of object { key, type, value } or unknown` + - `conversation: optional object { id }` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - - `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 conversation that this response was associated with. - - `key: string` + - `max_output_tokens: optional number` - The key to compare against the value. + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](/docs/guides/reasoning). - - `type: "eq" or "ne" or "gt" or 5 more` + - `max_tool_calls: optional number` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + 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. - - `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: optional object { input, output }` - - `"eq"` + Moderation results for the response input and output, if moderated completions were requested. - - `"ne"` + - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` - - `"gt"` + Moderation for the response input. - - `"gte"` + - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` - - `"lt"` + A moderation result produced for the response input or output. - - `"lte"` + - `categories: map[boolean]` - - `"in"` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `"nin"` + - `category_applied_input_types: map[array of "text" or "image"]` - - `value: string or number or boolean or array of string or number` + Which modalities of input are reflected by the score for each category. - The value to compare against the attribute key; supports string, number, or boolean types. + - `"text"` - - `string` + - `"image"` - - `number` + - `category_scores: map[number]` - - `boolean` + A dictionary of moderation categories to scores. - - `array of string or number` + - `flagged: boolean` - - `string` + A boolean indicating whether the content was flagged by any category. - - `number` + - `model: string` - - `unknown` + The moderation model that produced this result. - - `type: "and" or "or"` + - `type: "moderation_result"` - Type of operation: `and` or `or`. + The object type, which was always `moderation_result` for successful moderation results. - - `"and"` + - `"moderation_result"` - - `"or"` + - `Error object { code, message, type }` - - `max_num_results: optional number` + An error produced while attempting moderation for the response input or output. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `code: string` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + The error code. - Ranking options for search. + - `message: string` - - `hybrid_search: optional object { embedding_weight, text_weight }` + The error message. - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `type: "error"` - - `embedding_weight: number` + The object type, which was always `error` for moderation failures. - The weight of the embedding in the reciprocal ranking fusion. + - `"error"` - - `text_weight: number` + - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` - The weight of the text in the reciprocal ranking fusion. + Moderation for the response output. - - `ranker: optional "auto" or "default-2024-11-15"` + - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` - The ranker to use for the file search. + A moderation result produced for the response input or output. - - `"auto"` + - `categories: map[boolean]` - - `"default-2024-11-15"` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `score_threshold: optional number` + - `category_applied_input_types: map[array of "text" or "image"]` - 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. + Which modalities of input are reflected by the score for each category. - - `Computer object { type }` + - `"text"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `"image"` - - `type: "computer"` + - `category_scores: map[number]` - The type of the computer tool. Always `computer`. + A dictionary of moderation categories to scores. - - `"computer"` + - `flagged: boolean` - - `ComputerUsePreview object { display_height, display_width, environment, type }` + A boolean indicating whether the content was flagged by any category. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `model: string` - - `display_height: number` + The moderation model that produced this result. - The height of the computer display. + - `type: "moderation_result"` - - `display_width: number` + The object type, which was always `moderation_result` for successful moderation results. - The width of the computer display. + - `"moderation_result"` - - `environment: "windows" or "mac" or "linux" or 2 more` + - `Error object { code, message, type }` - The type of computer environment to control. + An error produced while attempting moderation for the response input or output. - - `"windows"` + - `code: string` - - `"mac"` + The error code. - - `"linux"` + - `message: string` - - `"ubuntu"` + The error message. - - `"browser"` + - `type: "error"` - - `type: "computer_use_preview"` + The object type, which was always `error` for moderation failures. - The type of the computer use tool. Always `computer_use_preview`. + - `"error"` - - `"computer_use_preview"` + - `output_text: optional string` - - `WebSearch object { type, filters, search_context_size, user_location }` + 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. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `previous_response_id: optional string` - - `type: "web_search" or "web_search_2025_08_26"` + 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 web search tool. One of `web_search` or `web_search_2025_08_26`. + - `prompt: optional BetaResponsePrompt` - - `"web_search"` + Reference to a prompt template and its variables. + [Learn more](/docs/guides/text?api-mode=responses#reusable-prompts). - - `"web_search_2025_08_26"` + - `id: string` - - `filters: optional object { allowed_domains }` + The unique identifier of the prompt template to use. - Filters for the search. + - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` - - `allowed_domains: optional array of 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. - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `string` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `search_context_size: optional "low" or "medium" or "high"` + A text input to the model. - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `"low"` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `"medium"` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `"high"` + A file input to the model. - - `user_location: optional object { city, country, region, 2 more }` + - `version: optional string` - The approximate location of the user. + Optional version of the prompt template. - - `city: optional string` + - `prompt_cache_key: optional string` - Free text input for the city of the user, e.g. `San Francisco`. + 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). - - `country: optional string` + - `prompt_cache_options: optional object { mode, ttl }` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - - `region: optional string` + - `mode: "implicit" or "explicit"` - Free text input for the region of the user, e.g. `California`. + Whether implicit prompt-cache breakpoints were enabled. - - `timezone: optional string` + - `"implicit"` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `"explicit"` - - `type: optional "approximate"` + - `ttl: "30m"` - The type of location approximation. Always `approximate`. + The minimum lifetime applied to each cache breakpoint. - - `"approximate"` + - `"30m"` - - `Mcp object { server_label, type, allowed_callers, 9 more }` + - `prompt_cache_retention: optional "in_memory" or "24h"` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + Deprecated. Use `prompt_cache_options.ttl` instead. - - `server_label: 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. - A label for this MCP server, used to identify it in tool calls. + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - - `type: "mcp"` + - 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 MCP tool. Always `mcp`. + - `"in_memory"` - - `"mcp"` + - `"24h"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `reasoning: optional object { context, effort, generate_summary, 2 more }` - The tool invocation context(s). + **gpt-5 and o-series models only** - - `"direct"` + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - `"programmatic"` + - `context: optional "auto" or "current_turn" or "all_turns"` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + Controls which reasoning items are rendered back to the model on later turns. + When returned on a response, this is the effective reasoning context mode + used for the response. - List of allowed tool names or a filter object. + - `"auto"` - - `McpAllowedTools = array of string` + - `"current_turn"` - A string array of allowed tool names + - `"all_turns"` - - `McpToolFilter object { read_only, tool_names }` + - `effort: optional "none" or "minimal" or "low" or 4 more` - A filter object to specify which tools are allowed. + 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. - - `read_only: optional boolean` + - `"none"` - 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. + - `"minimal"` - - `tool_names: optional array of string` + - `"low"` - List of allowed tool names. + - `"medium"` - - `authorization: optional string` + - `"high"` - 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. + - `"xhigh"` - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + - `"max"` - 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + - `generate_summary: optional "auto" or "concise" or "detailed"` - Currently supported `connector_id` values are: + **Deprecated:** use `summary` instead. - - 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 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`. - - `"connector_dropbox"` + - `"auto"` - - `"connector_gmail"` + - `"concise"` - - `"connector_googlecalendar"` + - `"detailed"` - - `"connector_googledrive"` + - `mode: optional string or "standard" or "pro"` - - `"connector_microsoftteams"` + Controls the reasoning execution mode for the request. - - `"connector_outlookcalendar"` + When returned on a response, this is the effective execution mode. - - `"connector_outlookemail"` + - `string` - - `"connector_sharepoint"` + - `"standard" or "pro"` - - `defer_loading: optional boolean` + Controls the reasoning execution mode for the request. - Whether this MCP tool is deferred and discovered via tool search. + When returned on a response, this is the effective execution mode. - - `headers: optional map[string]` + - `"standard"` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `"pro"` - - `require_approval: optional object { always, never } or "always" or "never"` + - `summary: optional "auto" or "concise" or "detailed"` - Specify which of the MCP server's tools require approval. + 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`. - - `McpToolApprovalFilter object { always, never }` + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `"auto"` - - `always: optional object { read_only, tool_names }` + - `"concise"` - A filter object to specify which tools are allowed. + - `"detailed"` - - `read_only: optional boolean` + - `safety_identifier: 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 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). - - `tool_names: optional array of string` + - `service_tier: optional "auto" or "default" or "flex" or 2 more` - List of allowed tool names. + Specifies the processing type used for serving the request. - - `never: optional 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'. - A filter object to specify which tools are allowed. + 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. - - `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. + - `"default"` - - `tool_names: optional array of string` + - `"flex"` - List of allowed tool names. + - `"scale"` - - `McpToolApprovalSetting = "always" or "never"` + - `"priority"` - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + - `status: optional BetaResponseStatus` - - `"always"` + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - - `"never"` + - `"completed"` - - `server_description: optional string` + - `"failed"` - Optional description of the MCP server, used to provide more context. + - `"in_progress"` - - `server_url: optional string` + - `"cancelled"` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `"queued"` - - `tunnel_id: optional string` + - `"incomplete"` - 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. + - `text: optional BetaResponseTextConfig` - - `CodeInterpreter object { container, type, allowed_callers }` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - A tool that runs Python code to help generate a response to a prompt. + - [Text inputs and outputs](/docs/guides/text) + - [Structured Outputs](/docs/guides/structured-outputs) - - `container: string or object { type, file_ids, memory_limit, network_policy }` + - `format: optional BetaResponseFormatTextConfig` - 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. + An object specifying the format that the model must output. - - `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 container ID. + The default format is `{ "type": "text" }` with no additional options. - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + **Not recommended for gpt-4o and newer models:** - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + 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. - - `type: "auto"` + - `Text object { type }` - Always `auto`. + Default response format. Used to generate text responses. - - `"auto"` + - `type: "text"` - - `file_ids: optional array of string` + The type of response format being defined. Always `text`. - An optional list of uploaded files to make available to your code. + - `"text"` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` - The memory limit for the code interpreter container. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - - `"1g"` + - `name: string` - - `"4g"` + 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. - - `"16g"` + - `schema: map[unknown]` - - `"64g"` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `type: "json_schema"` - Network access policy for the container. + The type of response format being defined. Always `json_schema`. - - `BetaContainerNetworkPolicyDisabled object { type }` + - `"json_schema"` - - `type: "disabled"` + - `description: optional string` - Disable outbound network access. Always `disabled`. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `"disabled"` + - `strict: optional boolean` - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + 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). - - `allowed_domains: array of string` + - `JSONObject object { type }` - A list of allowed domains when type is `allowlist`. + 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: "allowlist"` + - `type: "json_object"` - Allow outbound network access only to specified domains. Always `allowlist`. + The type of response format being defined. Always `json_object`. - - `"allowlist"` + - `"json_object"` - - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` + - `verbosity: optional "low" or "medium" or "high"` - Optional domain-scoped secrets for allowlisted domains. + 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`. - - `domain: string` + - `"low"` - The domain associated with the secret. + - `"medium"` - - `name: string` + - `"high"` - The name of the secret to inject for the domain. + - `top_logprobs: optional number` - - `value: 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 secret value to inject for the domain. + - `truncation: optional "auto" or "disabled"` - - `type: "code_interpreter"` + The truncation strategy to use for the model response. - The type of the code interpreter tool. Always `code_interpreter`. + - `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. - - `"code_interpreter"` + - `"auto"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"disabled"` - The tool invocation context(s). + - `usage: optional BetaResponseUsage` - - `"direct"` + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - - `"programmatic"` + - `input_tokens: number` - - `ProgrammaticToolCalling object { type }` + The number of input tokens. - - `type: "programmatic_tool_calling"` + - `input_tokens_details: object { cache_write_tokens, cached_tokens }` - The type of the tool. Always `programmatic_tool_calling`. + A detailed breakdown of the input tokens. - - `"programmatic_tool_calling"` + - `cache_write_tokens: number` - - `ImageGeneration object { type, action, background, 9 more }` + The number of input tokens that were written to the cache. - A tool that generates images using the GPT image models. + - `cached_tokens: number` - - `type: "image_generation"` + The number of tokens that were retrieved from the cache. + [More on prompt caching](/docs/guides/prompt-caching). - The type of the image generation tool. Always `image_generation`. + - `output_tokens: number` - - `"image_generation"` + The number of output tokens. - - `action: optional "generate" or "edit" or "auto"` + - `output_tokens_details: object { reasoning_tokens }` - Whether to generate a new image or edit an existing image. Default: `auto`. + A detailed breakdown of the output tokens. - - `"generate"` + - `reasoning_tokens: number` - - `"edit"` + The number of reasoning tokens. - - `"auto"` + - `total_tokens: number` - - `background: optional "transparent" or "opaque" or "auto"` + The total number of tokens used. - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + - `user: optional string` - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + 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). - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `sequence_number: number` - - `"transparent"` + The sequence number of this event. - - `"opaque"` + - `type: "response.in_progress"` - - `"auto"` + The type of the event. Always `response.in_progress`. - - `input_fidelity: optional "high" or "low"` + - `"response.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`. + - `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). +### Beta Response Includable - - `file_id: optional string` +- `BetaResponseIncludable = "file_search_call.results" or "web_search_call.results" or "web_search_call.action.sources" or 5 more` - File ID for the mask image. + Specify additional output data to include in the model response. Currently supported values are: - - `image_url: optional 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). - Base64-encoded mask image. + - `"file_search_call.results"` - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `"web_search_call.results"` - The image generation model to use. Default: `gpt-image-1`. + - `"web_search_call.action.sources"` - - `string` + - `"message.input_image.image_url"` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `"computer_call_output.output.image_url"` - The image generation model to use. Default: `gpt-image-1`. + - `"code_interpreter_call.outputs"` - - `"gpt-image-1"` + - `"reasoning.encrypted_content"` - - `"gpt-image-1-mini"` + - `"message.output_text.logprobs"` - - `"gpt-image-2"` +### Beta Response Incomplete Event - - `"gpt-image-2-2026-04-21"` +- `BetaResponseIncompleteEvent object { response, sequence_number, type, agent }` - - `"gpt-image-1.5"` + An event that is emitted when a response finishes as incomplete. - - `"chatgpt-image-latest"` + - `response: BetaResponse` - - `moderation: optional "auto" or "low"` + The response that was incomplete. - Moderation level for the generated image. Default: `auto`. + - `id: string` - - `"auto"` + Unique identifier for this Response. - - `"low"` + - `created_at: number` - - `output_compression: optional number` + Unix timestamp (in seconds) of when this Response was created. - Compression level for the output image. Default: 100. + - `error: BetaResponseError` - - `output_format: optional "png" or "webp" or "jpeg"` + An error object returned when the model fails to generate a Response. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 16 more` - - `"png"` + The error code for the response. - - `"webp"` + - `"server_error"` - - `"jpeg"` + - `"rate_limit_exceeded"` - - `partial_images: optional number` + - `"invalid_prompt"` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `"bio_policy"` - - `quality: optional "low" or "medium" or "high" or "auto"` + - `"vector_store_timeout"` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `"invalid_image"` - - `"low"` + - `"invalid_image_format"` - - `"medium"` + - `"invalid_base64_image"` - - `"high"` + - `"invalid_image_url"` - - `"auto"` + - `"image_too_large"` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `"image_too_small"` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `"image_parse_error"` - - `string` + - `"image_content_policy_violation"` - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `"invalid_image_mode"` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `"image_file_too_large"` - - `"1024x1024"` + - `"unsupported_image_media_type"` - - `"1024x1536"` + - `"empty_image_file"` - - `"1536x1024"` + - `"failed_to_download_image"` - - `"auto"` + - `"image_file_not_found"` - - `LocalShell object { type }` + - `message: string` - A tool that allows the model to execute shell commands in a local environment. + A human-readable description of the error. - - `type: "local_shell"` + - `incomplete_details: object { reason }` - The type of the local shell tool. Always `local_shell`. + Details about why the response is incomplete. - - `"local_shell"` + - `reason: optional "max_output_tokens" or "content_filter"` - - `Shell object { type, allowed_callers, environment }` + The reason why the response is incomplete. - A tool that allows the model to execute shell commands. + - `"max_output_tokens"` - - `type: "shell"` + - `"content_filter"` - The type of the shell tool. Always `shell`. + - `instructions: string or array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` - - `"shell"` + A system (or developer) message inserted into the model's context. - - `allowed_callers: optional array of "direct" or "programmatic"` + 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 tool invocation context(s). + - `string` - - `"direct"` + A text input to the model, equivalent to a text input with the + `developer` role. - - `"programmatic"` + - `InputItemList = array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + A list of one or many input items to the model, containing + different content types. - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `BetaEasyInputMessage object { content, role, phase, type }` - - `type: "container_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. - Automatically creates a container for this request + - `content: string or BetaResponseInputMessageContentList` - - `"container_auto"` + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `file_ids: optional array of string` + - `TextInput = string` - An optional list of uploaded files to make available to your code. + A text input to the model. - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `BetaResponseInputMessageContentList = array of BetaResponseInputContent` - The memory limit for the container. + A list of one or many input items to the model, containing different content + types. - - `"1g"` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `"4g"` + A text input to the model. - - `"16g"` + - `text: string` - - `"64g"` + The text input to the model. - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `type: "input_text"` - Network access policy for the container. + The type of the input item. Always `input_text`. - - `BetaContainerNetworkPolicyDisabled object { type }` + - `"input_text"` - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `prompt_cache_breakpoint: optional object { mode }` - - `skills: optional array of BetaSkillReference or BetaInlineSkill` + Marks the exact end of a reusable 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 optional list of skills referenced by id or inline data. + - `mode: "explicit"` - - `BetaSkillReference object { skill_id, type, version }` + The breakpoint mode. Always `explicit`. - - `skill_id: string` + - `"explicit"` - The ID of the referenced skill. + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `type: "skill_reference"` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - References a skill created with the /v1/skills endpoint. + - `detail: "low" or "high" or "auto" or "original"` - - `"skill_reference"` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `version: optional string` + - `"low"` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `"high"` - - `BetaInlineSkill object { description, name, source, type }` + - `"auto"` - - `description: string` + - `"original"` - The description of the skill. + - `type: "input_image"` - - `name: string` + The type of the input item. Always `input_image`. - The name of the skill. + - `"input_image"` - - `source: BetaInlineSkillSource` + - `file_id: optional string` - Inline skill payload + The ID of the file to be sent to the model. - - `data: string` + - `image_url: optional string` - Base64-encoded skill zip bundle. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `media_type: "application/zip"` + - `prompt_cache_breakpoint: optional object { mode }` - The media type of the inline skill payload. Must be `application/zip`. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `"application/zip"` + - `mode: "explicit"` - - `type: "base64"` + The breakpoint mode. Always `explicit`. - The type of the inline skill source. Must be `base64`. + - `"explicit"` - - `"base64"` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `type: "inline"` + A file input to the model. - Defines an inline skill for this request. + - `type: "input_file"` - - `"inline"` + The type of the input item. Always `input_file`. - - `BetaLocalEnvironment object { type, skills }` + - `"input_file"` - - `type: "local"` + - `detail: optional "auto" or "low" or "high"` - Use a local computer environment. + 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`. - - `"local"` + - `"auto"` - - `skills: optional array of BetaLocalSkill` + - `"low"` - An optional list of skills. + - `"high"` - - `description: string` + - `file_data: optional string` - The description of the skill. + The content of the file to be sent to the model. - - `name: string` + - `file_id: optional string` - The name of the skill. + The ID of the file to be sent to the model. - - `path: string` + - `file_url: optional string` - The path to the directory containing the skill. + The URL of the file to be sent to the model. - - `BetaContainerReference object { container_id, type }` + - `filename: optional string` - - `container_id: string` + The name of the file to be sent to the model. - The ID of the referenced container. + - `prompt_cache_breakpoint: optional object { mode }` - - `type: "container_reference"` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - References a container created with the /v1/containers endpoint + - `mode: "explicit"` - - `"container_reference"` + The breakpoint mode. Always `explicit`. - - `Custom object { name, type, allowed_callers, 3 more }` + - `"explicit"` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `role: "user" or "assistant" or "system" or "developer"` - - `name: string` + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - The name of the custom tool, used to identify it in tool calls. + - `"user"` - - `type: "custom"` + - `"assistant"` - The type of the custom tool. Always `custom`. + - `"system"` - - `"custom"` + - `"developer"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `phase: optional "commentary" or "final_answer"` - The tool invocation context(s). + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - `"direct"` + - `"commentary"` - - `"programmatic"` + - `"final_answer"` - - `defer_loading: optional boolean` + - `type: optional "message"` - Whether this tool should be deferred and discovered via tool search. + The type of the message input. Always `message`. - - `description: optional string` + - `"message"` - Optional description of the custom tool, used to provide more context. + - `Message object { content, role, agent, 2 more }` - - `format: optional object { type } or object { definition, syntax, 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. - The input format for the custom tool. Default is unconstrained text. + - `content: BetaResponseInputMessageContentList` - - `Text object { type }` + A list of one or many input items to the model, containing different content + types. - Unconstrained free-form text. + - `role: "user" or "system" or "developer"` - - `type: "text"` + The role of the message input. One of `user`, `system`, or `developer`. - Unconstrained text format. Always `text`. + - `"user"` - - `"text"` + - `"system"` - - `Grammar object { definition, syntax, type }` + - `"developer"` - 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`. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"lark"` + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"regex"` + - `"in_progress"` - - `type: "grammar"` + - `"completed"` - Grammar format. Always `grammar`. + - `"incomplete"` - - `"grammar"` + - `type: optional "message"` - - `Namespace object { description, name, tools, type }` + The type of the message input. Always set to `message`. - Groups function/custom tools under a shared namespace. + - `"message"` - - `description: string` + - `BetaResponseOutputMessage object { id, content, role, 4 more }` - A description of the namespace shown to the model. + An output message from the model. - - `name: string` + - `id: string` - The namespace name used in tool calls (for example, `crm`). + The unique ID of the output message. - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - The function/custom tools available inside this namespace. + The content of the output message. - - `Function object { name, type, allowed_callers, 5 more }` + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - - `name: string` + A text output from the model. - - `type: "function"` + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` - - `"function"` + The annotations of the text output. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `FileCitation object { file_id, filename, index, type }` - The tool invocation context(s). + A citation to a file. - - `"direct"` + - `file_id: string` - - `"programmatic"` + The ID of the file. - - `defer_loading: optional boolean` + - `filename: string` - Whether this function should be deferred and discovered via tool search. + The filename of the file cited. - - `description: optional string` + - `index: number` - - `output_schema: optional map[unknown]` + The index of the file in the list of files. - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `type: "file_citation"` - - `parameters: optional unknown` + The type of the file citation. Always `file_citation`. - - `strict: optional boolean` + - `"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. + - `URLCitation object { end_index, start_index, title, 2 more }` - - `Custom object { name, type, allowed_callers, 3 more }` + A citation for a web resource used to generate a model response. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `end_index: number` - - `name: string` + The index of the last character of the URL citation in the message. - The name of the custom tool, used to identify it in tool calls. + - `start_index: number` - - `type: "custom"` + The index of the first character of the URL citation in the message. - The type of the custom tool. Always `custom`. + - `title: string` - - `"custom"` + The title of the web resource. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `type: "url_citation"` - The tool invocation context(s). + The type of the URL citation. Always `url_citation`. - - `"direct"` + - `"url_citation"` - - `"programmatic"` + - `url: string` - - `defer_loading: optional boolean` + The URL of the web resource. - Whether this tool should be deferred and discovered via tool search. + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - - `description: optional string` + A citation for a container file used to generate a model response. - Optional description of the custom tool, used to provide more context. + - `container_id: string` - - `format: optional object { type } or object { definition, syntax, type }` + The ID of the container file. - The input format for the custom tool. Default is unconstrained text. + - `end_index: number` - - `Text object { type }` + The index of the last character of the container file citation in the message. - Unconstrained free-form text. + - `file_id: string` - - `type: "text"` + The ID of the file. - Unconstrained text format. Always `text`. + - `filename: string` - - `"text"` + The filename of the container file cited. - - `Grammar object { definition, syntax, type }` + - `start_index: number` - A grammar defined by the user. + The index of the first character of the container file citation in the message. - - `definition: string` + - `type: "container_file_citation"` - The grammar definition. + The type of the container file citation. Always `container_file_citation`. - - `syntax: "lark" or "regex"` + - `"container_file_citation"` - The syntax of the grammar definition. One of `lark` or `regex`. + - `FilePath object { file_id, index, type }` - - `"lark"` + A path to a file. - - `"regex"` + - `file_id: string` - - `type: "grammar"` + The ID of the file. - Grammar format. Always `grammar`. + - `index: number` - - `"grammar"` + The index of the file in the list of files. - - `type: "namespace"` + - `type: "file_path"` - The type of the tool. Always `namespace`. + The type of the file path. Always `file_path`. - - `"namespace"` + - `"file_path"` - - `ToolSearch object { type, description, execution, parameters }` + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - Hosted or BYOT tool search configuration for deferred tools. + - `token: string` - - `type: "tool_search"` + - `bytes: array of number` - The type of the tool. Always `tool_search`. + - `logprob: number` - - `"tool_search"` + - `top_logprobs: array of object { token, bytes, logprob }` - - `description: optional string` + - `token: string` - Description shown to the model for a client-executed tool search tool. + - `bytes: array of number` - - `execution: optional "server" or "client"` + - `logprob: number` - Whether tool search is executed by the server or by the client. + - `text: string` - - `"server"` + The text output from the model. - - `"client"` + - `type: "output_text"` - - `parameters: optional unknown` + The type of the output text. Always `output_text`. - Parameter schema for a client-executed tool search tool. + - `"output_text"` - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + - `BetaResponseOutputRefusal object { refusal, 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 refusal from the model. - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `refusal: string` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + The refusal explanation from the model. - - `"web_search_preview"` + - `type: "refusal"` - - `"web_search_preview_2025_03_11"` + The type of the refusal. Always `refusal`. - - `search_content_types: optional array of "text" or "image"` + - `"refusal"` - - `"text"` + - `role: "assistant"` - - `"image"` + The role of the output message. Always `assistant`. - - `search_context_size: optional "low" or "medium" or "high"` + - `"assistant"` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `status: "in_progress" or "completed" or "incomplete"` - - `"low"` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `"medium"` + - `"in_progress"` - - `"high"` + - `"completed"` - - `user_location: optional object { type, city, country, 2 more }` + - `"incomplete"` - The user's location. + - `type: "message"` - - `type: "approximate"` + The type of the output message. Always `message`. - The type of location approximation. Always `approximate`. + - `"message"` - - `"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`. + - `phase: optional "commentary" or "final_answer"` - - `region: 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. - Free text input for the region of the user, e.g. `California`. + - `"commentary"` - - `timezone: optional string` + - `"final_answer"` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `FileSearchCall object { id, queries, status, 3 more }` - - `ApplyPatch object { type, allowed_callers }` + The results of a file search tool call. See the + [file search guide](/docs/guides/tools-file-search) for more information. - Allows the assistant to create, delete, or update files using unified diffs. + - `id: string` - - `type: "apply_patch"` + The unique ID of the file search tool call. - The type of the tool. Always `apply_patch`. + - `queries: array of string` - - `"apply_patch"` + The queries used to search for files. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `status: "in_progress" or "searching" or "completed" or 2 more` - The tool invocation context(s). + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `"direct"` + - `"in_progress"` - - `"programmatic"` + - `"searching"` - - `type: "tool_search_output"` + - `"completed"` - The item type. Always `tool_search_output`. + - `"incomplete"` - - `"tool_search_output"` + - `"failed"` - - `id: optional string` + - `type: "file_search_call"` - The unique ID of this tool search output. + The type of the file search tool call. Always `file_search_call`. + + - `"file_search_call"` - `agent: optional object { agent_name }` @@ -113742,1055 +111987,1002 @@ 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. + - `results: optional array of object { attributes, file_id, filename, 2 more }` - - `"in_progress"` + The results of the file search tool call. - - `"completed"` + - `attributes: optional map[string or number or boolean]` - - `"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. Keys are strings + with a maximum length of 64 characters. Values are strings with a maximum + length of 512 characters, booleans, or numbers. - - `AdditionalTools object { role, tools, type, 2 more }` + - `string` - - `role: "developer"` + - `number` - The role that provided the additional tools. Only `developer` is supported. + - `boolean` - - `"developer"` + - `file_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 file. - A list of additional tools made available at this item. + - `filename: optional string` - - `Function object { name, parameters, strict, 5 more }` + The name of the file. - 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). + - `score: optional number` - - `name: string` + The relevance score of the file - a value between 0 and 1. - The name of the function to call. + - `text: optional string` - - `parameters: map[unknown]` + The text that was retrieved from the file. - A JSON schema object describing the parameters of the function. + - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` - - `strict: boolean` + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - Whether strict parameter validation is enforced for this function tool. + - `id: string` - - `type: "function"` + The unique ID of the computer call. - The type of the function tool. Always `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"` + - `id: string` - - `"programmatic"` + The ID of the pending safety check. - - `defer_loading: optional boolean` + - `code: optional string` - Whether this function is deferred and loaded via tool search. + The type of the pending safety check. - - `description: optional string` + - `message: optional string` - A description of the function. Used by the model to determine whether or not to call the function. + Details about the pending safety check. - - `output_schema: optional map[unknown]` + - `status: "in_progress" or "completed" or "incomplete"` - A JSON schema object describing the JSON value encoded in string outputs for this function. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + - `"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). + - `"completed"` - - `type: "file_search"` + - `"incomplete"` - The type of the file search tool. Always `file_search`. + - `type: "computer_call"` - - `"file_search"` + The type of the computer call. Always `computer_call`. - - `vector_store_ids: array of string` + - `"computer_call"` - The IDs of the vector stores to search. + - `action: optional BetaComputerAction` - - `filters: optional object { key, type, value } or object { filters, type }` + A click action. - A filter to apply. + - `Click object { button, type, x, 2 more }` - - `ComparisonFilter object { key, type, value }` + A click action. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `button: "left" or "right" or "wheel" or 2 more` - - `key: string` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - The key to compare against the value. + - `"left"` - - `type: "eq" or "ne" or "gt" or 5 more` + - `"right"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `"wheel"` - - `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 + - `"back"` - - `"eq"` + - `"forward"` - - `"ne"` + - `type: "click"` - - `"gt"` + Specifies the event type. For a click action, this property is always `click`. - - `"gte"` + - `"click"` - - `"lt"` + - `x: number` - - `"lte"` + The x-coordinate where the click occurred. - - `"in"` + - `y: number` - - `"nin"` + The y-coordinate where the click occurred. - - `value: string or number or boolean or array of string or number` + - `keys: optional array of string` - The value to compare against the attribute key; supports string, number, or boolean types. + The keys being held while clicking. - - `string` + - `DoubleClick object { keys, type, x, y }` - - `number` + A double click action. - - `boolean` + - `keys: array of string` - - `array of string or number` + The keys being held while double-clicking. - - `string` + - `type: "double_click"` - - `number` + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `CompoundFilter object { filters, type }` + - `"double_click"` - Combine multiple filters using `and` or `or`. + - `x: number` - - `filters: array of object { key, type, value } or unknown` + The x-coordinate where the double click occurred. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `y: number` - - `ComparisonFilter object { key, type, value }` + The y-coordinate where the double click occurred. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `Drag object { path, type, keys }` - - `key: string` + A drag action. - The key to compare against the value. + - `path: array of object { x, y }` - - `type: "eq" or "ne" or "gt" or 5 more` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `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 + - `x: number` - - `"eq"` + The x-coordinate. - - `"ne"` + - `y: number` - - `"gt"` + The y-coordinate. - - `"gte"` + - `type: "drag"` - - `"lt"` + Specifies the event type. For a drag action, this property is always set to `drag`. - - `"lte"` + - `"drag"` - - `"in"` + - `keys: optional array of string` - - `"nin"` + The keys being held while dragging the mouse. - - `value: string or number or boolean or array of string or number` + - `Keypress object { keys, type }` - The value to compare against the attribute key; supports string, number, or boolean types. + A collection of keypresses the model would like to perform. - - `string` + - `keys: array of string` - - `number` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `boolean` + - `type: "keypress"` - - `array of string or number` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `string` + - `"keypress"` - - `number` + - `Move object { type, x, y, keys }` - - `unknown` + A mouse move action. - - `type: "and" or "or"` + - `type: "move"` - Type of operation: `and` or `or`. + Specifies the event type. For a move action, this property is always set to `move`. - - `"and"` + - `"move"` - - `"or"` + - `x: number` - - `max_num_results: optional number` + The x-coordinate to move to. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `y: number` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + The y-coordinate to move to. - Ranking options for search. + - `keys: optional array of string` - - `hybrid_search: optional object { embedding_weight, text_weight }` + The keys being held while moving the mouse. - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `Screenshot object { type }` - - `embedding_weight: number` + A screenshot action. - The weight of the embedding in the reciprocal ranking fusion. + - `type: "screenshot"` - - `text_weight: number` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - The weight of the text in the reciprocal ranking fusion. + - `"screenshot"` - - `ranker: optional "auto" or "default-2024-11-15"` + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - The ranker to use for the file search. + A scroll action. - - `"auto"` + - `scroll_x: number` - - `"default-2024-11-15"` + The horizontal scroll distance. - - `score_threshold: optional number` + - `scroll_y: number` - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + The vertical scroll distance. - - `Computer object { 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`. - - `type: "computer"` + - `"scroll"` - The type of the computer tool. Always `computer`. + - `x: number` - - `"computer"` + The x-coordinate where the scroll occurred. - - `ComputerUsePreview object { display_height, display_width, environment, type }` + - `y: number` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The y-coordinate where the scroll occurred. - - `display_height: number` + - `keys: optional array of string` - The height of the computer display. + The keys being held while scrolling. - - `display_width: number` + - `Type object { text, type }` - The width of the computer display. + An action to type in text. - - `environment: "windows" or "mac" or "linux" or 2 more` + - `text: string` - The type of computer environment to control. + The text to type. - - `"windows"` + - `type: "type"` - - `"mac"` + Specifies the event type. For a type action, this property is always set to `type`. - - `"linux"` + - `"type"` - - `"ubuntu"` + - `Wait object { type }` - - `"browser"` + A wait action. - - `type: "computer_use_preview"` + - `type: "wait"` - The type of the computer use tool. Always `computer_use_preview`. + Specifies the event type. For a wait action, this property is always set to `wait`. - - `"computer_use_preview"` + - `"wait"` - - `WebSearch object { type, filters, search_context_size, user_location }` + - `actions: optional BetaComputerActionList` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `type: "web_search" or "web_search_2025_08_26"` + - `Click object { button, type, x, 2 more }` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + A click action. - - `"web_search"` + - `DoubleClick object { keys, type, x, y }` - - `"web_search_2025_08_26"` + A double click action. - - `filters: optional object { allowed_domains }` + - `Drag object { path, type, keys }` - Filters for the search. + A drag action. - - `allowed_domains: optional array of string` + - `Keypress object { keys, type }` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + A collection of keypresses the model would like to perform. - 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. + - `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 { city, country, region, 2 more }` + - `Type object { text, type }` - The approximate location of the user. + An action to type in text. - - `city: optional string` + - `Wait object { type }` - Free text input for the city of the user, e.g. `San Francisco`. + A wait action. - - `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` + - `ComputerCallOutput object { call_id, output, type, 4 more }` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The output of a computer tool call. - - `type: optional "approximate"` + - `call_id: string` - The type of location approximation. Always `approximate`. + The ID of the computer tool call that produced the output. - - `"approximate"` + - `output: BetaResponseComputerToolCallOutputScreenshot` - - `Mcp object { server_label, type, allowed_callers, 9 more }` + A computer screenshot image used with the computer use tool. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `type: "computer_screenshot"` - - `server_label: string` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - A label for this MCP server, used to identify it in tool calls. + - `"computer_screenshot"` - - `type: "mcp"` + - `file_id: optional string` - The type of the MCP tool. Always `mcp`. + The identifier of an uploaded file that contains the screenshot. - - `"mcp"` + - `image_url: optional string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The URL of the screenshot image. - 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"` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + - `id: optional string` - List of allowed tool names or a filter object. + The ID of the computer tool call output. - - `McpAllowedTools = array of string` + - `acknowledged_safety_checks: optional array of object { id, code, message }` - A string array of allowed tool names + The safety checks reported by the API that have been acknowledged by the developer. - - `McpToolFilter object { read_only, tool_names }` + - `id: string` - A filter object to specify which tools are allowed. + The ID of the pending safety check. - - `read_only: optional boolean` + - `code: 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 type of the pending safety check. - - `tool_names: optional array of string` + - `message: optional string` - List of allowed tool names. + Details about the pending safety check. - - `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](https://platform.openai.com/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 the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - - `"connector_dropbox"` + - `"in_progress"` - - `"connector_gmail"` + - `"completed"` - - `"connector_googlecalendar"` + - `"incomplete"` - - `"connector_googledrive"` + - `WebSearchCall object { id, action, status, 2 more }` - - `"connector_microsoftteams"` + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. - - `"connector_outlookcalendar"` + - `id: string` - - `"connector_outlookemail"` + The unique ID of the web search tool call. - - `"connector_sharepoint"` + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - - `defer_loading: 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). - Whether this MCP tool is deferred and discovered via tool search. + - `Search object { type, queries, query, sources }` - - `headers: optional map[string]` + Action type "search" - Performs a web search query. - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `type: "search"` - - `require_approval: optional object { always, never } or "always" or "never"` + The action type. - Specify which of the MCP server's tools require approval. + - `"search"` - - `McpToolApprovalFilter object { always, never }` + - `queries: optional array of 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 search queries. - - `always: optional object { read_only, tool_names }` + - `query: optional string` - A filter object to specify which tools are allowed. + The search query. - - `read_only: optional boolean` + - `sources: optional array of object { 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. + The sources used in the search. - - `tool_names: optional array of string` + - `type: "url"` - List of allowed tool names. + The type of source. Always `url`. - - `never: optional object { read_only, tool_names }` + - `"url"` - A filter object to specify which tools are allowed. + - `url: string` - - `read_only: optional boolean` + The URL of the source. - 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. + - `OpenPage object { type, url }` - - `tool_names: optional array of string` + Action type "open_page" - Opens a specific URL from search results. - List of allowed tool names. + - `type: "open_page"` - - `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. + - `"open_page"` - - `"always"` + - `url: optional string` - - `"never"` + The URL opened by the model. - - `server_description: optional string` + - `FindInPage object { pattern, type, url }` - Optional description of the MCP server, used to provide more context. + Action type "find_in_page": Searches for a pattern within a loaded page. - - `server_url: optional string` + - `pattern: string` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + The pattern or text to search for within the page. - - `tunnel_id: optional string` + - `type: "find_in_page"` - 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 action type. - - `CodeInterpreter object { container, type, allowed_callers }` + - `"find_in_page"` - 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 page searched for the pattern. - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + - `status: "in_progress" or "searching" or "completed" or "failed"` - - `string` + The status of the web search tool call. - The container ID. + - `"in_progress"` - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + - `"searching"` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `"completed"` - - `type: "auto"` + - `"failed"` - Always `auto`. + - `type: "web_search_call"` - - `"auto"` + The type of the web search tool call. Always `web_search_call`. - - `file_ids: optional array of string` + - `"web_search_call"` - 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 produced this item. - The memory limit for the code interpreter container. + - `agent_name: string` - - `"1g"` + The canonical name of the agent that produced this item. - - `"4g"` + - `FunctionCall object { arguments, call_id, name, 6 more }` - - `"16g"` + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. - - `"64g"` + - `arguments: string` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + A JSON string of the arguments to pass to the function. - Network access policy for the container. + - `call_id: string` - - `BetaContainerNetworkPolicyDisabled object { type }` + The unique ID of the function tool call generated by the model. - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `name: string` - - `type: "code_interpreter"` + The name of the function to run. - The type of the code interpreter tool. Always `code_interpreter`. + - `type: "function_call"` - - `"code_interpreter"` + The type of the function tool call. Always `function_call`. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"function_call"` - The tool invocation context(s). + - `id: optional string` - - `"direct"` + The unique ID of the function tool call. - - `"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"` + - `namespace: optional string` - - `background: optional "transparent" or "opaque" or "auto"` + The namespace of the function to run. - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + - `status: optional "in_progress" or "completed" or "incomplete"` - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `"in_progress"` - - `"transparent"` + - `"completed"` - - `"opaque"` + - `"incomplete"` - - `"auto"` + - `FunctionCallOutput object { call_id, output, type, 4 more }` - - `input_fidelity: optional "high" or "low"` + The output of a 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`. + - `call_id: string` - - `"high"` + The unique ID of the function tool call generated by the model. - - `"low"` + - `output: string or array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` - - `input_image_mask: optional object { file_id, image_url }` + Text, image, or file output of the function tool call. - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `string` - - `file_id: optional string` + A JSON string of the output of the function tool call. - File ID for the mask image. + - `array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` - - `image_url: optional string` + An array of content outputs (text, image, file) for the function tool call. - Base64-encoded mask image. + - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + A text input to the model. - The image generation model to use. Default: `gpt-image-1`. + - `text: string` - - `string` + The text input to the model. - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `type: "input_text"` - The image generation model to use. Default: `gpt-image-1`. + The type of the input item. Always `input_text`. - - `"gpt-image-1"` + - `"input_text"` - - `"gpt-image-1-mini"` + - `prompt_cache_breakpoint: optional object { mode }` - - `"gpt-image-2"` + Marks the exact end of a reusable 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-image-2-2026-04-21"` + - `mode: "explicit"` - - `"gpt-image-1.5"` + The breakpoint mode. Always `explicit`. - - `"chatgpt-image-latest"` + - `"explicit"` - - `moderation: optional "auto" or "low"` + - `BetaResponseInputImageContent object { type, detail, 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"` + - `type: "input_image"` - - `"low"` + The type of the input item. Always `input_image`. - - `output_compression: optional number` + - `"input_image"` - Compression level for the output image. Default: 100. + - `detail: optional "low" or "high" or "auto" or "original"` - - `output_format: optional "png" or "webp" or "jpeg"` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `"low"` - - `"png"` + - `"high"` - - `"webp"` + - `"auto"` - - `"jpeg"` + - `"original"` - - `partial_images: optional number` + - `file_id: optional string` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + The ID of the file to be sent to the model. - - `quality: optional "low" or "medium" or "high" or "auto"` + - `image_url: optional string` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `"low"` + - `prompt_cache_breakpoint: optional object { mode }` - - `"medium"` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `"high"` + - `mode: "explicit"` - - `"auto"` + The breakpoint mode. Always `explicit`. - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `"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`. + - `BetaResponseInputFileContent object { type, detail, file_data, 4 more }` - - `string` + A file input to the model. - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `type: "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`. + The type of the input item. Always `input_file`. - - `"1024x1024"` + - `"input_file"` - - `"1024x1536"` + - `detail: optional "auto" or "low" or "high"` - - `"1536x1024"` + 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"` - - `LocalShell object { type }` - - A tool that allows the model to execute shell commands in a local environment. + - `"low"` - - `type: "local_shell"` + - `"high"` - The type of the local shell tool. Always `local_shell`. + - `file_data: optional string` - - `"local_shell"` + The base64-encoded data of the file to be sent to the model. - - `Shell object { type, allowed_callers, environment }` + - `file_id: optional string` - A tool that allows the model to execute shell commands. + The ID of the file to be sent to the model. - - `type: "shell"` + - `file_url: optional string` - The type of the shell tool. Always `shell`. + The URL of the file to be sent to the model. - - `"shell"` + - `filename: optional string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The name of the file to be sent to the model. - 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"` - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + The breakpoint mode. Always `explicit`. - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `"explicit"` - - `BetaLocalEnvironment object { type, skills }` + - `type: "function_call_output"` - - `BetaContainerReference object { container_id, type }` + 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](https://platform.openai.com/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 }` - - `Namespace object { description, name, tools, type }` + An image input to the model. Learn about [image inputs](/docs/guides/vision) - Groups function/custom tools under a shared namespace. + - `EncryptedContent object { encrypted_content, type }` - - `description: string` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - A description of the namespace shown to the model. + - `encrypted_content: string` - - `name: string` + Opaque encrypted content. - The namespace name used in tool calls (for example, `crm`). + - `type: "encrypted_content"` - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + The type of the input item. Always `encrypted_content`. - The function/custom tools available inside this namespace. + - `"encrypted_content"` - - `Function object { name, type, allowed_callers, 5 more }` + - `recipient: string` - - `name: string` + The destination agent identity. - - `type: "function"` + - `type: "agent_message"` - - `"function"` + 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 function should be deferred and discovered via tool search. + - `agent_name: string` - - `description: optional string` + The canonical name of the agent that produced this item. - - `output_schema: optional map[unknown]` + - `MultiAgentCall object { action, arguments, call_id, 3 more }` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `parameters: optional unknown` + The multi-agent action that was executed. - - `strict: optional boolean` + - `"spawn_agent"` - 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. + - `"interrupt_agent"` - - `Custom object { name, type, allowed_callers, 3 more }` + - `"list_agents"` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `"send_message"` - - `name: string` + - `"followup_task"` - The name of the custom tool, used to identify it in tool calls. + - `"wait_agent"` - - `type: "custom"` + - `arguments: string` - The type of the custom tool. Always `custom`. + The action arguments as a JSON string. - - `"custom"` + - `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"` - - `defer_loading: optional boolean` + - `id: optional string` - Whether this tool should be deferred and discovered via tool search. + The unique ID of this multi-agent call. - - `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 }` + - `MultiAgentCallOutput object { action, call_id, output, 3 more }` - Unconstrained free-form text. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `type: "text"` + The multi-agent action that produced this result. - Unconstrained text format. Always `text`. + - `"spawn_agent"` - - `"text"` + - `"interrupt_agent"` - - `Grammar object { definition, syntax, type }` + - `"list_agents"` - A grammar defined by the user. + - `"send_message"` - - `definition: string` + - `"followup_task"` - The grammar definition. + - `"wait_agent"` - - `syntax: "lark" or "regex"` + - `call_id: string` - The syntax of the grammar definition. One of `lark` or `regex`. + The unique ID of the multi-agent call. - - `"lark"` + - `output: array of object { text, type, annotations }` - - `"regex"` + Text output returned by the multi-agent action. - - `type: "grammar"` + - `text: string` - Grammar format. Always `grammar`. + The text content. - - `"grammar"` + - `type: "output_text"` - - `type: "namespace"` + The content type. Always `output_text`. - The type of the tool. Always `namespace`. + - `"output_text"` - - `"namespace"` + - `annotations: optional array of object { file_id, filename, index, type } or array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` - - `ToolSearch object { type, description, execution, parameters }` + Citations associated with the text content. - Hosted or BYOT tool search configuration for deferred tools. + - `array of object { file_id, filename, index, type }` - - `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 file cited. - 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_citation"` - - `"server"` + The citation type. Always `file_citation`. - - `"client"` + - `"file_citation"` - - `parameters: optional unknown` + - `array of object { end_index, start_index, title, 2 more }` - Parameter schema for a client-executed tool search tool. + - `end_index: number` - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + The index of the last character of the citation in the 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). + - `start_index: number` - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + The index of the first character of the citation in the message. - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `title: string` - - `"web_search_preview"` + The title of the cited resource. - - `"web_search_preview_2025_03_11"` + - `type: "url_citation"` - - `search_content_types: optional array of "text" or "image"` + The citation type. Always `url_citation`. - - `"text"` + - `"url_citation"` - - `"image"` + - `url: string` - - `search_context_size: optional "low" or "medium" or "high"` + The URL of the cited resource. - 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. + - `array of object { container_id, end_index, file_id, 3 more }` - - `"low"` + - `container_id: string` - - `"medium"` + The ID of the container. - - `"high"` + - `end_index: number` - - `user_location: optional object { type, city, country, 2 more }` + The index of the last character of the citation in the message. - The user's location. + - `file_id: string` - - `type: "approximate"` + The ID of the container file. - The type of location approximation. Always `approximate`. + - `filename: string` - - `"approximate"` + 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 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 citation type. Always `container_file_citation`. - - `region: optional string` + - `"container_file_citation"` - Free text input for the region of the user, e.g. `California`. + - `type: "multi_agent_call_output"` - - `timezone: optional string` + The item type. Always `multi_agent_call_output`. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `"multi_agent_call_output"` - - `ApplyPatch object { type, allowed_callers }` + - `id: optional string` - Allows the assistant to create, delete, or update files using unified diffs. + The unique ID of this multi-agent call output. - - `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). + - `ToolSearchCall object { arguments, type, id, 4 more }` - - `"direct"` + - `arguments: unknown` - - `"programmatic"` + The arguments supplied to the tool search call. - - `type: "additional_tools"` + - `type: "tool_search_call"` - The item type. Always `additional_tools`. + The item type. Always `tool_search_call`. - - `"additional_tools"` + - `"tool_search_call"` - `id: optional string` - The unique ID of this additional tools item. + The unique ID of this tool search call. - `agent: optional object { agent_name }` @@ -114800,2219 +112992,2262 @@ 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](https://platform.openai.com/docs/guides/conversation-state). - - - `id: string` - - The unique identifier of the reasoning content. - - - `summary: array of object { text, type }` - - Reasoning summary content. + - `call_id: optional string` - - `text: string` + The unique ID of the tool search call generated by the model. - A summary of the reasoning output from the model so far. + - `execution: optional "server" or "client"` - - `type: "summary_text"` + Whether tool search was executed by the server or by the client. - The type of the object. Always `summary_text`. + - `"server"` - - `"summary_text"` + - `"client"` - - `type: "reasoning"` + - `status: optional "in_progress" or "completed" or "incomplete"` - The type of the object. Always `reasoning`. + The status of the tool search call. - - `"reasoning"` + - `"in_progress"` - - `agent: optional object { agent_name }` + - `"completed"` - The agent that produced this item. + - `"incomplete"` - - `agent_name: string` + - `ToolSearchOutput object { tools, type, id, 4 more }` - The canonical name of the agent that produced this 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` - - `content: optional array of object { text, type }` + The loaded tool definitions returned by the tool search output. - Reasoning text content. + - `Function object { name, parameters, strict, 5 more }` - - `text: string` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - The reasoning text from the model. + - `name: string` - - `type: "reasoning_text"` + The name of the function to call. - The type of the reasoning text. Always `reasoning_text`. + - `parameters: map[unknown]` - - `"reasoning_text"` + A JSON schema object describing the parameters of the function. - - `encrypted_content: optional string` + - `strict: boolean` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + Whether strict parameter validation is enforced for this function tool. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `type: "function"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The type of the function tool. Always `function`. - - `"in_progress"` + - `"function"` - - `"completed"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"incomplete"` + The tool invocation context(s). - - `Compaction object { encrypted_content, type, id, agent }` + - `"direct"` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `"programmatic"` - - `encrypted_content: string` + - `defer_loading: optional boolean` - The encrypted content of the compaction summary. + Whether this function is deferred and loaded via tool search. - - `type: "compaction"` + - `description: optional string` - The type of the item. Always `compaction`. + A description of the function. Used by the model to determine whether or not to call the function. - - `"compaction"` + - `output_schema: optional map[unknown]` - - `id: optional string` + A JSON schema object describing the JSON value encoded in string outputs for this function. - The ID of the compaction item. + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - - `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 produced this item. + - `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"` - - `ImageGenerationCall object { id, result, status, 2 more }` + - `vector_store_ids: array of string` - An image generation request made by the model. + 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 image generation call. + A filter to apply. - - `result: string` + - `ComparisonFilter object { key, type, value }` - The generated image encoded in base64. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `status: "in_progress" or "completed" or "generating" or "failed"` + - `key: string` - The status of the image generation call. + 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`. - - `"generating"` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `"failed"` + - `"eq"` - - `type: "image_generation_call"` + - `"ne"` - The type of the image generation call. Always `image_generation_call`. + - `"gt"` - - `"image_generation_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"` - - `CodeInterpreterCall object { id, code, container_id, 4 more }` + - `value: string or number or boolean or array of string or number` - A tool call to run code. + The value to compare against the attribute key; supports string, number, or boolean types. - - `id: string` + - `string` - The unique ID of the code interpreter tool call. + - `number` - - `code: string` + - `boolean` - The code to run, or null if not available. + - `array of string or number` - - `container_id: string` + - `string` - The ID of the container used to run the code. + - `number` - - `outputs: array of object { logs, type } or object { type, url }` + - `CompoundFilter object { filters, type }` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + Combine multiple filters using `and` or `or`. - - `Logs object { logs, type }` + - `filters: array of object { key, type, value } or unknown` - The logs output from the code interpreter. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `logs: string` + - `ComparisonFilter object { key, type, value }` - The logs output from the code interpreter. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `type: "logs"` + - `key: string` - The type of the output. Always `logs`. + The key to compare against the value. - - `"logs"` + - `type: "eq" or "ne" or "gt" or 5 more` - - `Image object { type, url }` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The image output from the code interpreter. + - `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: "image"` + - `"eq"` - The type of the output. Always `image`. + - `"ne"` - - `"image"` + - `"gt"` - - `url: string` + - `"gte"` - The URL of the image output from the code interpreter. + - `"lt"` - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + - `"lte"` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `"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. - - `"interpreting"` + - `string` - - `"failed"` + - `number` - - `type: "code_interpreter_call"` + - `boolean` - The type of the code interpreter tool call. Always `code_interpreter_call`. + - `array of string or number` - - `"code_interpreter_call"` + - `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`. - - `LocalShellCall object { id, action, call_id, 3 more }` + - `"and"` - A tool call to run a command on the local shell. + - `"or"` - - `id: string` + - `max_num_results: optional number` - The unique ID of the local shell call. + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `action: object { command, env, type, 3 more }` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - Execute a shell command on the server. + Ranking options for search. - - `command: array of string` + - `hybrid_search: optional object { embedding_weight, text_weight }` - The command to run. + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `env: map[string]` + - `embedding_weight: number` - Environment variables to set for the command. + The weight of the embedding in the reciprocal ranking fusion. - - `type: "exec"` + - `text_weight: number` - The type of the local shell action. Always `exec`. + The weight of the text in the reciprocal ranking fusion. - - `"exec"` + - `ranker: optional "auto" or "default-2024-11-15"` - - `timeout_ms: optional number` + The ranker to use for the file search. - Optional timeout in milliseconds for the command. + - `"auto"` - - `user: optional string` + - `"default-2024-11-15"` - Optional user to run the command as. + - `score_threshold: optional number` - - `working_directory: optional string` + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - Optional working directory to run the command in. + - `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 local shell tool call generated by the model. + - `type: "computer"` - - `status: "in_progress" or "completed" or "incomplete"` + The type of the computer tool. Always `computer`. - The status of the local shell call. + - `"computer"` - - `"in_progress"` + - `ComputerUsePreview object { display_height, display_width, environment, 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"` + - `display_height: number` - - `type: "local_shell_call"` + The height of the computer display. - The type of the local shell call. Always `local_shell_call`. + - `display_width: number` - - `"local_shell_call"` + The width of the computer display. - - `agent: optional object { agent_name }` + - `environment: "windows" or "mac" or "linux" or 2 more` - The agent that produced this item. + The type of computer environment to control. - - `agent_name: string` + - `"windows"` - The canonical name of the agent that produced this item. + - `"mac"` - - `LocalShellCallOutput object { id, output, type, 2 more }` + - `"linux"` - The output of a local shell tool call. + - `"ubuntu"` - - `id: string` + - `"browser"` - The unique ID of the local shell tool call generated by the model. + - `type: "computer_use_preview"` - - `output: string` + The type of the computer use tool. Always `computer_use_preview`. - A JSON string of the output of the local shell tool call. + - `"computer_use_preview"` - - `type: "local_shell_call_output"` + - `WebSearch object { type, filters, search_context_size, user_location }` - The type of the local shell tool call output. Always `local_shell_call_output`. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - - `"local_shell_call_output"` + - `type: "web_search" or "web_search_2025_08_26"` - - `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 produced this item. + - `"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 }` - - `status: optional "in_progress" or "completed" or "incomplete"` + Filters for the search. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `allowed_domains: optional array of string` - - `"in_progress"` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `"completed"` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `"incomplete"` + - `search_context_size: optional "low" or "medium" or "high"` - - `ShellCall object { action, call_id, type, 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. - A tool representing a request to execute one or more shell commands. + - `"low"` - - `action: object { commands, max_output_length, timeout_ms }` + - `"medium"` - The shell commands and limits that describe how to run the tool call. + - `"high"` - - `commands: array of string` + - `user_location: optional object { city, country, region, 2 more }` - Ordered shell commands for the execution environment to run. + The approximate location of the user. - - `max_output_length: optional number` + - `city: optional string` - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + Free text input for the city of the user, e.g. `San Francisco`. - - `timeout_ms: optional number` + - `country: optional string` - Maximum wall-clock time in milliseconds to allow the shell commands to run. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `call_id: string` + - `region: optional string` - The unique ID of the shell tool call generated by the model. + Free text input for the region of the user, e.g. `California`. - - `type: "shell_call"` + - `timezone: optional string` - The type of the item. Always `shell_call`. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `"shell_call"` + - `type: optional "approximate"` - - `id: optional string` + The type of location approximation. Always `approximate`. - The unique ID of the shell tool call. Populated when this item is returned via API. + - `"approximate"` - - `agent: optional object { agent_name }` + - `Mcp object { server_label, type, allowed_callers, 9 more }` - The agent that produced this item. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - - `agent_name: string` + - `server_label: string` - The canonical name of the agent that produced this item. + A label for this MCP server, used to identify it in tool calls. - - `caller: optional object { type } or object { caller_id, type }` + - `type: "mcp"` - The execution context that produced this tool call. + The type of the MCP tool. Always `mcp`. - - `Direct object { type }` + - `"mcp"` - - `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. + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `type: "program"` + List of allowed tool names or a filter object. - The caller type. Always `program`. + - `McpAllowedTools = array of string` - - `"program"` + A string array of allowed tool names - - `environment: optional BetaLocalEnvironment or BetaContainerReference` + - `McpToolFilter object { read_only, tool_names }` - The environment to execute the shell commands in. + A filter object to specify which tools are allowed. - - `BetaLocalEnvironment object { type, skills }` + - `read_only: optional boolean` - - `BetaContainerReference object { container_id, type }` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `tool_names: optional array of string` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + List of allowed tool names. - - `"in_progress"` + - `authorization: optional string` - - `"completed"` + 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. - - `"incomplete"` + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `ShellCallOutput object { call_id, output, type, 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). - The streamed output items emitted by a shell tool call. + Currently supported `connector_id` values are: - - `call_id: string` + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - The unique ID of the shell tool call generated by the model. + - `"connector_dropbox"` - - `output: array of BetaResponseFunctionShellCallOutputContent` + - `"connector_gmail"` - Captured chunks of stdout and stderr output, along with their associated outcomes. + - `"connector_googlecalendar"` - - `outcome: object { type } or object { exit_code, type }` + - `"connector_googledrive"` - The exit or timeout outcome associated with this shell call. + - `"connector_microsoftteams"` - - `Timeout object { type }` + - `"connector_outlookcalendar"` - Indicates that the shell call exceeded its configured time limit. + - `"connector_outlookemail"` - - `type: "timeout"` + - `"connector_sharepoint"` - The outcome type. Always `timeout`. + - `defer_loading: optional boolean` - - `"timeout"` + Whether this MCP tool is deferred and discovered via tool search. - - `Exit object { exit_code, type }` + - `headers: optional map[string]` - Indicates that the shell commands finished and returned an exit code. + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `exit_code: number` + - `require_approval: optional object { always, never } or "always" or "never"` - The exit code returned by the shell process. + Specify which of the MCP server's tools require approval. - - `type: "exit"` + - `McpToolApprovalFilter object { always, never }` - The outcome type. Always `exit`. + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `"exit"` + - `always: optional object { read_only, tool_names }` - - `stderr: string` + A filter object to specify which tools are allowed. - Captured stderr output for the shell call. + - `read_only: optional boolean` - - `stdout: 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 stdout output for the shell call. + - `tool_names: optional array of string` - - `type: "shell_call_output"` + List of allowed tool names. - The type of the item. Always `shell_call_output`. + - `never: optional object { read_only, tool_names }` - - `"shell_call_output"` + A filter object to specify which tools are allowed. - - `id: optional string` + - `read_only: optional boolean` - The unique ID of the shell tool call output. Populated when this item is returned via API. + 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. - The caller type. Always `direct`. + - `server_url: optional string` - - `"direct"` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `Program object { caller_id, type }` + - `tunnel_id: optional string` - - `caller_id: 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 call ID of the program item that produced this tool call. + - `CodeInterpreter object { container, type, allowed_callers }` - - `type: "program"` + A tool that runs Python code to help generate a response to a prompt. - The caller type. Always `program`. + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `"program"` + 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. - - `max_output_length: optional number` + - `string` - The maximum number of UTF-8 characters captured for this shell call's combined output. + The container ID. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - The status of the shell call output. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `"in_progress"` + - `type: "auto"` - - `"completed"` + Always `auto`. - - `"incomplete"` + - `"auto"` - - `ApplyPatchCall object { call_id, operation, status, 4 more }` + - `file_ids: optional array of string` - A tool call representing a request to create, delete, or update files using diff patches. + 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. - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + - `"1g"` - The specific create, delete, or update instruction for the apply_patch tool call. + - `"4g"` - - `CreateFile object { diff, path, type }` + - `"16g"` - Instruction for creating a new file via the apply_patch tool. + - `"64g"` - - `diff: string` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - Unified diff content to apply when creating the file. + Network access policy for the container. - - `path: string` + - `BetaContainerNetworkPolicyDisabled object { type }` - Path of the file to create relative to the workspace root. + - `type: "disabled"` - - `type: "create_file"` + Disable outbound network access. Always `disabled`. - The operation type. Always `create_file`. + - `"disabled"` - - `"create_file"` + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `DeleteFile object { path, type }` + - `allowed_domains: array of string` - Instruction for deleting an existing file via the apply_patch tool. + A list of allowed domains when type is `allowlist`. - - `path: string` + - `type: "allowlist"` - Path of the file to delete relative to the workspace root. + Allow outbound network access only to specified domains. Always `allowlist`. - - `type: "delete_file"` + - `"allowlist"` - The operation type. Always `delete_file`. + - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` - - `"delete_file"` + Optional domain-scoped secrets for allowlisted domains. - - `UpdateFile object { diff, path, type }` + - `domain: string` - Instruction for updating an existing file via the apply_patch tool. + The domain associated with the secret. - - `diff: string` + - `name: string` - Unified diff content to apply to the existing file. + The name of the secret to inject for the domain. - - `path: string` + - `value: string` - Path of the file to update relative to the workspace root. + The secret value to inject for the domain. - - `type: "update_file"` + - `type: "code_interpreter"` - The operation type. Always `update_file`. + The type of the code interpreter tool. Always `code_interpreter`. - - `"update_file"` + - `"code_interpreter"` - - `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"` + - `ProgrammaticToolCalling object { type }` - The type of the item. Always `apply_patch_call`. + - `type: "programmatic_tool_calling"` - - `"apply_patch_call"` + The type of the tool. Always `programmatic_tool_calling`. - - `id: optional string` + - `"programmatic_tool_calling"` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `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"` - The caller type. Always `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"` - The caller type. Always `program`. + - `input_fidelity: optional "high" or "low"` - - `"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`. - - `ApplyPatchCallOutput object { call_id, status, type, 4 more }` + - `"high"` - The streamed output emitted by an apply patch tool call. + - `"low"` - - `call_id: string` + - `input_image_mask: optional object { file_id, image_url }` - The unique ID of the apply patch tool call generated by the model. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `status: "completed" or "failed"` + - `file_id: optional string` - The status of the apply patch tool call output. One of `completed` or `failed`. + File ID for the mask image. - - `"completed"` + - `image_url: optional string` - - `"failed"` + Base64-encoded mask image. - - `type: "apply_patch_call_output"` + - `model: optional string or "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"` + - `string` - - `id: optional string` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + The image generation model to use. Default: `gpt-image-1`. - - `agent: optional object { agent_name }` + - `"gpt-image-1"` - The agent that produced this item. + - `"gpt-image-1-mini"` - - `agent_name: string` + - `"gpt-image-1.5"` - The canonical name of the agent that produced this item. + - `moderation: optional "auto" or "low"` - - `caller: optional object { type } or object { caller_id, type }` + Moderation level for the generated image. Default: `auto`. - The execution context that produced this tool call. + - `"auto"` - - `Direct object { type }` + - `"low"` - - `type: "direct"` + - `output_compression: optional number` - The caller type. Always `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"` - The caller type. Always `program`. + - `partial_images: optional number` - - `"program"` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `output: optional string` + - `quality: optional "low" or "medium" or "high" or "auto"` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `McpListTools object { id, server_label, tools, 3 more }` + - `"low"` - A list of tools available on an MCP server. + - `"medium"` - - `id: string` + - `"high"` - The unique ID of the list. + - `"auto"` - - `server_label: string` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - The label of the MCP server. + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `tools: array of object { input_schema, name, annotations, description }` + - `string` - The tools available on the server. + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `input_schema: unknown` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - The JSON schema describing the tool's input. + - `"1024x1024"` - - `name: string` + - `"1024x1536"` - The name of the tool. + - `"1536x1024"` - - `annotations: optional unknown` + - `"auto"` - Additional annotations about the tool. + - `LocalShell object { type }` - - `description: optional string` + A tool that allows the model to execute shell commands in a local environment. - The description of the tool. + - `type: "local_shell"` - - `type: "mcp_list_tools"` + The type of the local shell tool. Always `local_shell`. - The type of the item. Always `mcp_list_tools`. + - `"local_shell"` - - `"mcp_list_tools"` + - `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"` - - `error: optional string` + - `allowed_callers: optional array of "direct" or "programmatic"` - Error message if the server could not list tools. + The tool invocation context(s). - - `McpApprovalRequest object { id, arguments, name, 3 more }` + - `"direct"` - A request for human approval of a tool invocation. + - `"programmatic"` - - `id: string` + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - The unique ID of the approval request. + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - - `arguments: string` + - `type: "container_auto"` - A JSON string of arguments for the tool. + Automatically creates a container for this request - - `name: string` + - `"container_auto"` - The name of the tool to run. + - `file_ids: optional array of string` - - `server_label: string` + An optional list of uploaded files to make available to your code. - The label of the MCP server making the request. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `type: "mcp_approval_request"` + The memory limit for the container. - The type of the item. Always `mcp_approval_request`. + - `"1g"` - - `"mcp_approval_request"` + - `"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. - - `McpApprovalResponse object { approval_request_id, approve, type, 3 more }` + - `BetaContainerNetworkPolicyDisabled object { type }` - A response to an MCP approval request. + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `approval_request_id: string` + - `skills: optional array of BetaSkillReference or BetaInlineSkill` - The ID of the approval request being answered. + An optional list of skills referenced by id or inline data. - - `approve: boolean` + - `BetaSkillReference object { skill_id, type, version }` - Whether the request was approved. + - `skill_id: string` - - `type: "mcp_approval_response"` + The ID of the referenced skill. - The type of the item. Always `mcp_approval_response`. + - `type: "skill_reference"` - - `"mcp_approval_response"` + References a skill created with the /v1/skills endpoint. - - `id: optional string` + - `"skill_reference"` - The unique ID of the approval response + - `version: optional string` - - `agent: optional object { agent_name }` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - The agent that produced this item. + - `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. - - `reason: optional string` + - `name: string` - Optional reason for the decision. + The name of the skill. - - `McpCall object { id, arguments, name, 7 more }` + - `source: BetaInlineSkillSource` - An invocation of a tool on an MCP server. + Inline skill payload - - `id: string` + - `data: string` - The unique ID of the tool call. + Base64-encoded skill zip bundle. - - `arguments: string` + - `media_type: "application/zip"` - A JSON string of the arguments passed to the tool. + The media type of the inline skill payload. Must be `application/zip`. - - `name: string` + - `"application/zip"` - The name of the tool that was run. + - `type: "base64"` - - `server_label: string` + The type of the inline skill source. Must be `base64`. - The label of the MCP server running the tool. + - `"base64"` - - `type: "mcp_call"` + - `type: "inline"` - The type of the item. Always `mcp_call`. + Defines an inline skill for this request. - - `"mcp_call"` + - `"inline"` - - `agent: optional object { agent_name }` + - `BetaLocalEnvironment object { type, skills }` - The agent that produced this item. + - `type: "local"` - - `agent_name: string` + Use a local computer environment. - The canonical name of the agent that produced this item. + - `"local"` - - `approval_request_id: optional string` + - `skills: optional array of BetaLocalSkill` - 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. + An optional list of skills. - - `error: optional string` + - `description: string` - The error from the tool call, if any. + The description of the skill. - - `output: optional string` + - `name: string` - The output from the tool call. + The name of the skill. - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `path: string` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + The path to the directory containing the skill. - - `"in_progress"` + - `BetaContainerReference object { container_id, type }` - - `"completed"` + - `container_id: string` - - `"incomplete"` + The ID of the referenced container. - - `"calling"` + - `type: "container_reference"` - - `"failed"` + References a container created with the /v1/containers endpoint - - `CustomToolCallOutput object { call_id, output, type, 3 more }` + - `"container_reference"` - The output of a custom tool call from your code, being sent back to the model. + - `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](https://platform.openai.com/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. - - `type: "custom_tool_call_output"` + - `format: optional object { type } or object { definition, syntax, type }` - The type of the custom tool call output. Always `custom_tool_call_output`. + The input format for the custom tool. Default is unconstrained text. - - `"custom_tool_call_output"` + - `Text object { type }` - - `id: optional string` + Unconstrained free-form text. - The unique ID of the custom tool call output in the OpenAI platform. + - `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. - - `caller: optional object { type } or object { caller_id, type }` + - `definition: string` - The execution context that produced this tool call. + The grammar definition. - - `Direct object { type }` + - `syntax: "lark" or "regex"` - - `type: "direct"` + The syntax of the grammar definition. One of `lark` or `regex`. - The caller type. Always `direct`. + - `"lark"` - - `"direct"` + - `"regex"` - - `Program object { caller_id, type }` + - `type: "grammar"` - - `caller_id: string` + Grammar format. Always `grammar`. - The call ID of the program item that produced this tool call. + - `"grammar"` - - `type: "program"` + - `Namespace object { description, name, tools, type }` - The caller type. Always `program`. + Groups function/custom tools under a shared namespace. - - `"program"` + - `description: string` - - `CustomToolCall object { call_id, input, name, 5 more }` + A description of the namespace shown to the model. - A call to a custom tool created by the model. + - `name: string` - - `call_id: string` + The namespace name used in tool calls (for example, `crm`). - An identifier used to map this custom tool call to a tool call output. + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - - `input: string` + The function/custom tools available inside this namespace. - The input for the custom tool call generated by the model. + - `Function object { name, type, allowed_callers, 5 more }` - `name: string` - The name of the custom tool being called. + - `type: "function"` - - `type: "custom_tool_call"` + - `"function"` - The type of the custom tool call. Always `custom_tool_call`. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"custom_tool_call"` + The tool invocation context(s). - - `id: optional string` + - `"direct"` - The unique ID of the custom tool call in the OpenAI platform. + - `"programmatic"` - - `agent: optional object { agent_name }` + - `defer_loading: optional boolean` - The agent that produced this item. + Whether this function should be deferred and discovered via tool search. - - `agent_name: string` + - `description: optional string` - The canonical name of the agent that produced this item. + - `output_schema: optional map[unknown]` - - `caller: optional object { type } or object { caller_id, type }` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - The execution context that produced this tool call. + - `parameters: optional unknown` - - `Direct object { type }` + - `strict: optional boolean` - - `type: "direct"` + 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. - - `"direct"` + - `Custom object { name, type, allowed_callers, 3 more }` - - `Program object { caller_id, type }` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `caller_id: string` + - `name: string` - The call ID of the program item that produced this tool call. + The name of the custom tool, used to identify it in tool calls. - - `type: "program"` + - `type: "custom"` - - `"program"` + The type of the custom tool. Always `custom`. - - `namespace: optional string` + - `"custom"` - The namespace of the custom tool being called. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `CompactionTrigger object { type, agent }` + The tool invocation context(s). - Compacts the current context. Must be the final input item. + - `"direct"` - - `type: "compaction_trigger"` + - `"programmatic"` - The type of the item. Always `compaction_trigger`. + - `defer_loading: optional boolean` - - `"compaction_trigger"` + Whether this tool should be deferred and discovered via tool search. - - `agent: optional object { agent_name }` + - `description: optional string` - The agent that produced this item. + 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. - - `ItemReference object { id, agent, type }` + - `Text object { type }` - An internal identifier for an item to reference. + Unconstrained free-form text. - - `id: string` + - `type: "text"` - The ID of the item to reference. + 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` - - `type: optional "item_reference"` + The grammar definition. - The type of item to reference. Always `item_reference`. + - `syntax: "lark" or "regex"` - - `"item_reference"` + The syntax of the grammar definition. One of `lark` or `regex`. - - `Program object { id, call_id, code, 3 more }` + - `"lark"` - - `id: string` + - `"regex"` - The unique ID of this program item. + - `type: "grammar"` - - `call_id: string` + Grammar format. Always `grammar`. - The stable call ID of the program item. + - `"grammar"` - - `code: string` + - `type: "namespace"` - The JavaScript source executed by programmatic tool calling. + The type of the tool. Always `namespace`. - - `fingerprint: string` + - `"namespace"` - Opaque program replay fingerprint that must be round-tripped. + - `ToolSearch object { type, description, execution, parameters }` - - `type: "program"` + Hosted or BYOT tool search configuration for deferred tools. - The item type. Always `program`. + - `type: "tool_search"` - - `"program"` + 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"` - - `ProgramOutput object { id, call_id, result, 3 more }` + Whether tool search is executed by the server or by the client. - - `id: string` + - `"server"` - The unique ID of this program output item. + - `"client"` - - `call_id: string` + - `parameters: optional unknown` - The call ID of the program item. + Parameter schema for a client-executed tool search tool. - - `result: string` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - The result produced by the program 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). - - `status: "completed" or "incomplete"` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - The terminal status of the program output. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `"completed"` + - `"web_search_preview"` - - `"incomplete"` + - `"web_search_preview_2025_03_11"` - - `type: "program_output"` + - `search_content_types: optional array of "text" or "image"` - The item type. Always `program_output`. + - `"text"` - - `"program_output"` + - `"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"` - - `metadata: map[string]` + - `"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. + - `user_location: optional object { type, city, country, 2 more }` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The user's location. - - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` + - `type: "approximate"` - 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](https://platform.openai.com/docs/models) - to browse and compare available models. + The type of location approximation. Always `approximate`. - - `"gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more` + - `"approximate"` - 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](https://platform.openai.com/docs/models) - to browse and compare available models. + - `city: optional string` - - `"gpt-5.6-sol"` + Free text input for the city of the user, e.g. `San Francisco`. - - `"gpt-5.6-terra"` + - `country: optional string` - - `"gpt-5.6-luna"` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `"gpt-5.4"` + - `region: optional string` - - `"gpt-5.4-mini"` + Free text input for the region of the user, e.g. `California`. - - `"gpt-5.4-nano"` + - `timezone: optional string` - - `"gpt-5.4-mini-2026-03-17"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `"gpt-5.4-nano-2026-03-17"` + - `ApplyPatch object { type, allowed_callers }` - - `"gpt-5.3-chat-latest"` + Allows the assistant to create, delete, or update files using unified diffs. - - `"gpt-5.2"` + - `type: "apply_patch"` - - `"gpt-5.2-2025-12-11"` + The type of the tool. Always `apply_patch`. - - `"gpt-5.2-chat-latest"` + - `"apply_patch"` - - `"gpt-5.2-pro"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"gpt-5.2-pro-2025-12-11"` + The tool invocation context(s). - - `"gpt-5.1"` + - `"direct"` - - `"gpt-5.1-2025-11-13"` + - `"programmatic"` - - `"gpt-5.1-codex"` + - `type: "tool_search_output"` - - `"gpt-5.1-mini"` + The item type. Always `tool_search_output`. - - `"gpt-5.1-chat-latest"` + - `"tool_search_output"` - - `"gpt-5"` + - `id: optional string` - - `"gpt-5-mini"` + The unique ID of this tool search output. - - `"gpt-5-nano"` + - `agent: optional object { agent_name }` - - `"gpt-5-2025-08-07"` + The agent that produced this item. - - `"gpt-5-mini-2025-08-07"` + - `agent_name: string` - - `"gpt-5-nano-2025-08-07"` + The canonical name of the agent that produced this item. - - `"gpt-5-chat-latest"` + - `call_id: optional string` - - `"gpt-4.1"` + The unique ID of the tool search call generated by the model. - - `"gpt-4.1-mini"` + - `execution: optional "server" or "client"` - - `"gpt-4.1-nano"` + Whether tool search was executed by the server or by the client. - - `"gpt-4.1-2025-04-14"` + - `"server"` - - `"gpt-4.1-mini-2025-04-14"` + - `"client"` - - `"gpt-4.1-nano-2025-04-14"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"o4-mini"` + The status of the tool search output. - - `"o4-mini-2025-04-16"` + - `"in_progress"` - - `"o3"` + - `"completed"` - - `"o3-2025-04-16"` + - `"incomplete"` + + - `AdditionalTools object { role, tools, type, 2 more }` - - `"o3-mini"` + - `role: "developer"` - - `"o3-mini-2025-01-31"` + The role that provided the additional tools. Only `developer` is supported. - - `"o1"` + - `"developer"` - - `"o1-2024-12-17"` + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - - `"o1-preview"` + A list of additional tools made available at this item. - - `"o1-preview-2024-09-12"` + - `Function object { name, parameters, strict, 5 more }` - - `"o1-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). - - `"o1-mini-2024-09-12"` + - `name: string` - - `"gpt-4o"` + The name of the function to call. - - `"gpt-4o-2024-11-20"` + - `parameters: map[unknown]` - - `"gpt-4o-2024-08-06"` + A JSON schema object describing the parameters of the function. - - `"gpt-4o-2024-05-13"` + - `strict: boolean` - - `"gpt-4o-audio-preview"` + Whether strict parameter validation is enforced for this function tool. - - `"gpt-4o-audio-preview-2024-10-01"` + - `type: "function"` - - `"gpt-4o-audio-preview-2024-12-17"` + The type of the function tool. Always `function`. - - `"gpt-4o-audio-preview-2025-06-03"` + - `"function"` - - `"gpt-4o-mini-audio-preview"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"gpt-4o-mini-audio-preview-2024-12-17"` + The tool invocation context(s). - - `"gpt-4o-search-preview"` + - `"direct"` - - `"gpt-4o-mini-search-preview"` + - `"programmatic"` - - `"gpt-4o-search-preview-2025-03-11"` + - `defer_loading: optional boolean` - - `"gpt-4o-mini-search-preview-2025-03-11"` + Whether this function is deferred and loaded via tool search. - - `"chatgpt-4o-latest"` + - `description: optional string` - - `"codex-mini-latest"` + A description of the function. Used by the model to determine whether or not to call the function. - - `"gpt-4o-mini"` + - `output_schema: optional map[unknown]` - - `"gpt-4o-mini-2024-07-18"` + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `"gpt-4-turbo"` + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - - `"gpt-4-turbo-2024-04-09"` + 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-4-0125-preview"` + - `type: "file_search"` - - `"gpt-4-turbo-preview"` + The type of the file search tool. Always `file_search`. - - `"gpt-4-1106-preview"` + - `"file_search"` - - `"gpt-4-vision-preview"` + - `vector_store_ids: array of string` - - `"gpt-4"` + The IDs of the vector stores to search. - - `"gpt-4-0314"` + - `filters: optional object { key, type, value } or object { filters, type }` - - `"gpt-4-0613"` + A filter to apply. - - `"gpt-4-32k"` + - `ComparisonFilter object { key, type, value }` - - `"gpt-4-32k-0314"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `"gpt-4-32k-0613"` + - `key: string` - - `"gpt-3.5-turbo"` + The key to compare against the value. - - `"gpt-3.5-turbo-16k"` + - `type: "eq" or "ne" or "gt" or 5 more` - - `"gpt-3.5-turbo-0301"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `"gpt-3.5-turbo-0613"` + - `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-3.5-turbo-1106"` + - `"eq"` - - `"gpt-3.5-turbo-0125"` + - `"ne"` - - `"gpt-3.5-turbo-16k-0613"` + - `"gt"` - - `"o1-pro"` + - `"gte"` - - `"o1-pro-2025-03-19"` + - `"lt"` - - `"o3-pro"` + - `"lte"` - - `"o3-pro-2025-06-10"` + - `"in"` - - `"o3-deep-research"` + - `"nin"` - - `"o3-deep-research-2025-06-26"` + - `value: string or number or boolean or array of string or number` - - `"o4-mini-deep-research"` + The value to compare against the attribute key; supports string, number, or boolean types. - - `"o4-mini-deep-research-2025-06-26"` + - `string` - - `"computer-use-preview"` + - `number` - - `"computer-use-preview-2025-03-11"` + - `boolean` - - `"gpt-5-codex"` + - `array of string or number` - - `"gpt-5-pro"` + - `string` - - `"gpt-5-pro-2025-10-06"` + - `number` - - `"gpt-5.1-codex-max"` + - `CompoundFilter object { filters, type }` - - `string` + Combine multiple filters using `and` or `or`. - - `object: "response"` + - `filters: array of object { key, type, value } or unknown` - The object type of this resource - always set to `response`. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `"response"` + - `ComparisonFilter object { key, type, value }` - - `output: array of BetaResponseOutputItem` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - An array of content items generated by the model. + - `key: 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 key to compare against the value. - - `BetaResponseOutputMessage object { id, content, role, 4 more }` + - `type: "eq" or "ne" or "gt" or 5 more` - An output message from the model. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `FileSearchCall object { id, queries, status, 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 - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `"eq"` - - `id: string` + - `"ne"` - The unique ID of the file search tool call. + - `"gt"` - - `queries: array of string` + - `"gte"` - The queries used to search for files. + - `"lt"` - - `status: "in_progress" or "searching" or "completed" or 2 more` + - `"lte"` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `"in"` - - `"in_progress"` + - `"nin"` - - `"searching"` + - `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` - - `"failed"` + - `number` - - `type: "file_search_call"` + - `boolean` - The type of the file search tool call. Always `file_search_call`. + - `array of string or number` - - `"file_search_call"` + - `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`. - - `results: optional array of object { attributes, file_id, filename, 2 more }` + - `"and"` - The results of the file search tool call. + - `"or"` - - `attributes: optional map[string or number or boolean]` + - `max_num_results: 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. Keys are strings - with a maximum length of 64 characters. Values are strings with a maximum - length of 512 characters, booleans, or numbers. + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `string` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `number` + Ranking options for search. - - `boolean` + - `hybrid_search: optional object { embedding_weight, text_weight }` - - `file_id: optional 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 file. + - `embedding_weight: number` - - `filename: optional string` + The weight of the embedding in the reciprocal ranking fusion. - The name of the file. + - `text_weight: number` - - `score: optional number` + The weight of the text in the reciprocal ranking fusion. - The relevance score of the file - a value between 0 and 1. + - `ranker: optional "auto" or "default-2024-11-15"` - - `text: optional string` + The ranker to use for the file search. - The text that was retrieved from the file. + - `"auto"` - - `FunctionCall object { arguments, call_id, name, 6 more }` + - `"default-2024-11-15"` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `score_threshold: optional number` - - `arguments: 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. - A JSON string of the arguments to pass to the function. + - `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 function tool call generated by the model. + - `type: "computer"` - - `name: string` + The type of the computer tool. Always `computer`. - The name of the function to run. + - `"computer"` - - `type: "function_call"` + - `ComputerUsePreview object { display_height, display_width, environment, type }` - The type of the function tool call. Always `function_call`. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"function_call"` + - `display_height: number` - - `id: optional string` + The height of the computer display. - The unique ID of the function tool call. + - `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"` - - `caller: optional object { type } or object { caller_id, type }` + - `"mac"` - The execution context that produced this tool call. + - `"linux"` - - `Direct object { type }` + - `"ubuntu"` - - `type: "direct"` + - `"browser"` - - `"direct"` + - `type: "computer_use_preview"` - - `Program object { caller_id, type }` + The type of the computer use tool. Always `computer_use_preview`. - - `caller_id: string` + - `"computer_use_preview"` - The call ID of the program item that produced this tool call. + - `WebSearch object { type, filters, search_context_size, user_location }` - - `type: "program"` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - - `"program"` + - `type: "web_search" or "web_search_2025_08_26"` - - `namespace: optional string` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - The namespace of the function to run. + - `"web_search"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"web_search_2025_08_26"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `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. - - `FunctionCallOutput object { id, call_id, output, 5 more }` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `id: string` + - `search_context_size: optional "low" or "medium" or "high"` - The unique ID of the function call tool 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. - - `call_id: string` + - `"low"` - The unique ID of the function tool call generated by the model. + - `"medium"` - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `"high"` - The output from the function call generated by your code. - Can be a string or an list of output content. + - `user_location: optional object { city, country, region, 2 more }` - - `StringOutput = string` + The approximate location of the user. - A string of the output of the function call. + - `city: optional string` - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + Free text input for the city of the user, e.g. `San Francisco`. - Text, image, or file output of the function call. + - `country: optional string` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - A text input to the model. + - `region: optional string` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + Free text input for the region of the user, e.g. `California`. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `timezone: optional string` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - A file input to the model. + - `type: optional "approximate"` - - `status: "in_progress" or "completed" or "incomplete"` + The type of location approximation. Always `approximate`. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"approximate"` - - `"in_progress"` + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `"completed"` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - - `"incomplete"` + - `server_label: string` - - `type: "function_call_output"` + A label for this MCP server, used to identify it in tool calls. - The type of the function tool call output. Always `function_call_output`. + - `type: "mcp"` - - `"function_call_output"` + 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` - The caller type. Always `direct`. + A string array of allowed tool names - - `"direct"` + - `McpToolFilter 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` - The caller type. Always `program`. + List of allowed tool names. - - `"program"` + - `authorization: optional string` - - `created_by: 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 identifier of the actor that created the item. + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `AgentMessage object { id, author, content, 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). - - `id: string` + Currently supported `connector_id` values are: - The unique ID of the agent 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` - - `author: string` + - `"connector_dropbox"` - The sending agent identity. + - `"connector_gmail"` - - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` + - `"connector_googlecalendar"` - Encrypted content sent between agents. + - `"connector_googledrive"` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `"connector_microsoftteams"` - A text input to the model. + - `"connector_outlookcalendar"` - - `BetaResponseOutputText object { annotations, text, type, logprobs }` + - `"connector_outlookemail"` - A text output from the model. + - `"connector_sharepoint"` - - `Text object { text, type }` + - `defer_loading: optional boolean` - A text content. + Whether this MCP tool is deferred and discovered via tool search. - - `text: string` + - `headers: optional map[string]` - - `type: "text"` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `"text"` + - `require_approval: optional object { always, never } or "always" or "never"` - - `SummaryText object { text, type }` + Specify which of the MCP server's tools require approval. - A summary text from the model. + - `McpToolApprovalFilter object { always, never }` - - `text: 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 summary of the reasoning output from the model so far. + - `always: optional object { read_only, tool_names }` - - `type: "summary_text"` + A filter object to specify which tools are allowed. - The type of the object. Always `summary_text`. + - `read_only: optional boolean` - - `"summary_text"` + 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. - - `ReasoningText object { text, type }` + - `tool_names: optional array of string` - Reasoning text from the model. + List of allowed tool names. - - `text: string` + - `never: optional object { read_only, tool_names }` - The reasoning text from the model. + A filter object to specify which tools are allowed. - - `type: "reasoning_text"` + - `read_only: optional boolean` - The type of the reasoning text. Always `reasoning_text`. + 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. - - `"reasoning_text"` + - `tool_names: optional array of string` - - `BetaResponseOutputRefusal object { refusal, type }` + List of allowed tool names. - A refusal from the model. + - `McpToolApprovalSetting = "always" or "never"` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `"always"` - - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` + - `"never"` - A screenshot of a computer. + - `server_description: optional string` - - `detail: "low" or "high" or "auto" or "original"` + Optional description of the MCP server, used to provide more context. - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `server_url: optional string` - - `"low"` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `"high"` + - `tunnel_id: optional string` - - `"auto"` + 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. - - `"original"` + - `CodeInterpreter object { container, type, allowed_callers }` - - `file_id: string` + A tool that runs Python code to help generate a response to a prompt. - The identifier of an uploaded file that contains the screenshot. + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `image_url: 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 URL of the screenshot image. + - `string` - - `type: "computer_screenshot"` + The container ID. - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - - `"computer_screenshot"` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `prompt_cache_breakpoint: optional object { mode }` + - `type: "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. + Always `auto`. - - `mode: "explicit"` + - `"auto"` - The breakpoint mode. Always `explicit`. + - `file_ids: optional array of string` - - `"explicit"` + An optional list of uploaded files to make available to your code. - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - A file input to the model. + The memory limit for the code interpreter container. - - `EncryptedContent object { encrypted_content, type }` + - `"1g"` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `"4g"` - - `encrypted_content: string` + - `"16g"` - Opaque encrypted content. + - `"64g"` - - `type: "encrypted_content"` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - The type of the input item. Always `encrypted_content`. + Network access policy for the container. - - `"encrypted_content"` + - `BetaContainerNetworkPolicyDisabled object { type }` - - `recipient: string` + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - The destination agent identity. + - `type: "code_interpreter"` - - `type: "agent_message"` + The type of the code interpreter tool. Always `code_interpreter`. - The type of the item. Always `agent_message`. + - `"code_interpreter"` - - `"agent_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. + - `ProgrammaticToolCalling object { type }` - - `MultiAgentCall object { id, action, arguments, 3 more }` + - `type: "programmatic_tool_calling"` - - `id: string` + The type of the tool. Always `programmatic_tool_calling`. - The unique ID of the multi-agent call item. + - `"programmatic_tool_calling"` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `ImageGeneration object { type, action, background, 9 more }` - The multi-agent action to execute. + A tool that generates images using the GPT image models. - - `"spawn_agent"` + - `type: "image_generation"` - - `"interrupt_agent"` + The type of the image generation tool. Always `image_generation`. - - `"list_agents"` + - `"image_generation"` - - `"send_message"` + - `action: optional "generate" or "edit" or "auto"` - - `"followup_task"` + Whether to generate a new image or edit an existing image. Default: `auto`. - - `"wait_agent"` + - `"generate"` - - `arguments: string` + - `"edit"` - The JSON string of arguments generated for the action. + - `"auto"` - - `call_id: string` + - `background: optional "transparent" or "opaque" or "auto"` - The unique ID linking this call to its output. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - - `type: "multi_agent_call"` + - `"transparent"` - The type of the multi-agent call. Always `multi_agent_call`. + - `"opaque"` - - `"multi_agent_call"` + - `"auto"` - - `agent: optional object { agent_name }` + - `input_fidelity: optional "high" or "low"` - 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`. - - `agent_name: string` + - `"high"` - The canonical name of the agent that produced this item. + - `"low"` - - `MultiAgentCallOutput object { id, action, call_id, 3 more }` + - `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 multi-agent call output item. + - `file_id: optional string` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + File ID for the mask image. - The multi-agent action that produced this result. + - `image_url: optional string` - - `"spawn_agent"` + Base64-encoded mask image. - - `"interrupt_agent"` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `"list_agents"` + The image generation model to use. Default: `gpt-image-1`. - - `"send_message"` + - `string` - - `"followup_task"` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `"wait_agent"` + The image generation model to use. Default: `gpt-image-1`. - - `call_id: string` + - `"gpt-image-1"` - The unique ID of the multi-agent call. + - `"gpt-image-1-mini"` - - `output: array of BetaResponseOutputText` + - `"gpt-image-1.5"` - Text output returned by the multi-agent action. + - `moderation: optional "auto" 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 }` + Moderation level for the generated image. Default: `auto`. - The annotations of the text output. + - `"auto"` - - `text: string` + - `"low"` - The text output from the model. + - `output_compression: optional number` - - `type: "output_text"` + Compression level for the output image. Default: 100. - The type of the output text. Always `output_text`. + - `output_format: optional "png" or "webp" or "jpeg"` - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `type: "multi_agent_call_output"` + - `"png"` - The type of the multi-agent result. Always `multi_agent_call_output`. + - `"webp"` - - `"multi_agent_call_output"` + - `"jpeg"` - - `agent: optional object { agent_name }` + - `partial_images: optional number` - The agent that produced this item. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `agent_name: string` + - `quality: optional "low" or "medium" or "high" or "auto"` - The canonical name of the agent that produced this item. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `WebSearchCall object { id, action, status, 2 more }` + - `"low"` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `"medium"` - - `id: string` + - `"high"` - The unique ID of the web search tool call. + - `"auto"` - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "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). + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `Search object { type, queries, query, sources }` + - `string` - Action type "search" - Performs a web search query. + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `type: "search"` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - The action type. + - `"1024x1024"` - - `"search"` + - `"1024x1536"` - - `queries: optional array of string` + - `"1536x1024"` - The search queries. + - `"auto"` - - `query: optional string` + - `LocalShell object { type }` - The search query. + A tool that allows the model to execute shell commands in a local environment. - - `sources: optional array of object { type, url }` + - `type: "local_shell"` - The sources used in the search. + The type of the local shell tool. Always `local_shell`. - - `type: "url"` + - `"local_shell"` - The type of source. Always `url`. + - `Shell object { type, allowed_callers, environment }` - - `"url"` + A tool that allows the model to execute shell commands. - - `url: string` + - `type: "shell"` - The URL of the source. + The type of the shell tool. Always `shell`. - - `OpenPage object { type, url }` + - `"shell"` - Action type "open_page" - Opens a specific URL from search results. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `type: "open_page"` + The tool invocation context(s). - The action type. + - `"direct"` - - `"open_page"` + - `"programmatic"` - - `url: optional string` + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - The URL opened by the model. + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - - `FindInPage object { pattern, type, url }` + - `BetaLocalEnvironment object { type, skills }` - Action type "find_in_page": Searches for a pattern within a loaded page. + - `BetaContainerReference object { container_id, type }` - - `pattern: string` + - `Custom object { name, type, allowed_callers, 3 more }` - The pattern or text to search for within the page. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `type: "find_in_page"` + - `name: string` - The action type. + The name of the custom tool, used to identify it in tool calls. - - `"find_in_page"` + - `type: "custom"` - - `url: string` + The type of the custom tool. Always `custom`. - The URL of the page searched for the pattern. + - `"custom"` - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `allowed_callers: optional array of "direct" or "programmatic"` - The status of the web search tool call. + The tool invocation context(s). - - `"in_progress"` + - `"direct"` - - `"searching"` + - `"programmatic"` - - `"completed"` + - `defer_loading: optional boolean` - - `"failed"` + Whether this tool should be deferred and discovered via tool search. - - `type: "web_search_call"` + - `description: optional string` - The type of the web search tool call. Always `web_search_call`. + Optional description of the custom tool, used to provide more context. - - `"web_search_call"` + - `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"` - - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` + Unconstrained text format. Always `text`. - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + - `"text"` - - `id: string` + - `Grammar object { definition, syntax, type }` - The unique ID of the computer call. + A grammar defined by the user. - - `call_id: string` + - `definition: string` - An identifier used when responding to the tool call with output. + The grammar definition. - - `pending_safety_checks: array of object { id, code, message }` + - `syntax: "lark" or "regex"` - The pending safety checks for the computer call. + The syntax of the grammar definition. One of `lark` or `regex`. - - `id: string` + - `"lark"` - The ID of the pending safety check. + - `"regex"` - - `code: optional string` + - `type: "grammar"` - The type of the pending safety check. + Grammar format. Always `grammar`. - - `message: optional string` + - `"grammar"` - Details about the pending safety check. + - `Namespace object { description, name, tools, type }` - - `status: "in_progress" or "completed" or "incomplete"` + Groups function/custom tools under a shared namespace. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `description: string` - - `"in_progress"` + A description of the namespace shown to the model. - - `"completed"` + - `name: string` - - `"incomplete"` + The namespace name used in tool calls (for example, `crm`). - - `type: "computer_call"` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - The type of the computer call. Always `computer_call`. + The function/custom tools available inside this namespace. - - `"computer_call"` + - `Function object { name, type, allowed_callers, 5 more }` - - `action: optional BetaComputerAction` + - `name: string` - A click action. + - `type: "function"` - - `actions: optional BetaComputerActionList` + - `"function"` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `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` - - `ComputerCallOutput object { id, call_id, output, 5 more }` + Whether this function should be deferred and discovered via tool search. - - `id: string` + - `description: optional string` - The unique ID of the computer call tool output. + - `output_schema: optional map[unknown]` - - `call_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 computer tool call that produced the output. + - `parameters: optional unknown` - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `strict: optional boolean` - A computer screenshot image used with the computer use 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. - - `status: "completed" or "incomplete" or "failed" or "in_progress"` + - `Custom 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. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `"completed"` + - `name: string` - - `"incomplete"` + The name of the custom tool, used to identify it in tool calls. - - `"failed"` + - `type: "custom"` - - `"in_progress"` + The type of the custom tool. Always `custom`. - - `type: "computer_call_output"` + - `"custom"` - 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` + - `defer_loading: optional boolean` - The ID of the pending safety check. + Whether this tool should be deferred and discovered via tool search. - - `code: optional string` + - `description: optional string` - The type of the pending safety check. + Optional description of the custom tool, used to provide more context. - - `message: optional string` + - `format: optional object { type } or object { definition, syntax, type }` - Details about the pending safety check. + 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`. - - `created_by: optional string` + - `"text"` - The identifier of the actor that created the item. + - `Grammar object { definition, syntax, type }` - - `Reasoning object { id, summary, type, 4 more }` + A grammar defined by the user. - 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](https://platform.openai.com/docs/guides/conversation-state). + - `definition: string` - - `id: string` + The grammar definition. - The unique identifier of the reasoning content. + - `syntax: "lark" or "regex"` - - `summary: array of object { text, type }` + The syntax of the grammar definition. One of `lark` or `regex`. - Reasoning summary content. + - `"lark"` - - `text: string` + - `"regex"` - A summary of the reasoning output from the model so far. + - `type: "grammar"` - - `type: "summary_text"` + Grammar format. Always `grammar`. - The type of the object. Always `summary_text`. + - `"grammar"` - - `"summary_text"` + - `type: "namespace"` - - `type: "reasoning"` + The type of the tool. Always `namespace`. - The type of the object. Always `reasoning`. + - `"namespace"` - - `"reasoning"` + - `ToolSearch object { type, description, execution, parameters }` - - `agent: optional object { agent_name }` + Hosted or BYOT tool search configuration for deferred tools. - The agent that produced this item. + - `type: "tool_search"` - - `agent_name: string` + The type of the tool. Always `tool_search`. - The canonical name of the agent that produced this item. + - `"tool_search"` - - `content: optional array of object { text, type }` + - `description: optional string` - Reasoning text content. + Description shown to the model for a client-executed tool search tool. - - `text: string` + - `execution: optional "server" or "client"` - The reasoning text from the model. + Whether tool search is executed by the server or by the client. - - `type: "reasoning_text"` + - `"server"` - The type of the reasoning text. Always `reasoning_text`. + - `"client"` - - `"reasoning_text"` + - `parameters: optional unknown` - - `encrypted_content: optional string` + Parameter schema for a client-executed tool search tool. - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - - `status: optional "in_progress" or "completed" or "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). - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `"in_progress"` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `"completed"` + - `"web_search_preview"` - - `"incomplete"` + - `"web_search_preview_2025_03_11"` - - `Program object { id, call_id, code, 3 more }` + - `search_content_types: optional array of "text" or "image"` - - `id: string` + - `"text"` - The unique ID of the program item. + - `"image"` - - `call_id: string` + - `search_context_size: optional "low" or "medium" or "high"` - The stable call ID of the program item. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `code: string` + - `"low"` - The JavaScript source executed by programmatic tool calling. + - `"medium"` - - `fingerprint: string` + - `"high"` - Opaque program replay fingerprint that must be round-tripped. + - `user_location: optional object { type, city, country, 2 more }` - - `type: "program"` + The user's location. - The type of the item. Always `program`. + - `type: "approximate"` - - `"program"` + 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` - - `ProgramOutput object { id, call_id, result, 3 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 program output item. + Free text input for the region of the user, e.g. `California`. - - `call_id: string` + - `timezone: optional string` - The call ID of the program item. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `result: string` + - `ApplyPatch object { type, allowed_callers }` - The result produced by the program item. + Allows the assistant to create, delete, or update files using unified diffs. - - `status: "completed" or "incomplete"` + - `type: "apply_patch"` - The terminal status of the program output item. + The type of the tool. Always `apply_patch`. - - `"completed"` + - `"apply_patch"` - - `"incomplete"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `type: "program_output"` + The tool invocation context(s). - The type of the item. Always `program_output`. + - `"direct"` - - `"program_output"` + - `"programmatic"` - - `agent: optional object { agent_name }` + - `type: "additional_tools"` - The agent that produced this item. + The item type. Always `additional_tools`. - - `agent_name: string` + - `"additional_tools"` - The canonical name of the agent that produced this item. + - `id: optional string` - - `ToolSearchCall object { id, arguments, call_id, 5 more }` + The unique ID of this additional tools item. - - `id: string` + - `agent: optional object { agent_name }` - The unique ID of the tool search call item. + The agent that produced this item. - - `arguments: unknown` + - `agent_name: string` - Arguments used for the tool search call. + The canonical name of the agent that produced this item. - - `call_id: 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: "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: "in_progress" or "completed" or "incomplete"` + - `text: string` - The status of the tool search call item that was recorded. + A summary of the reasoning output from the model so far. - - `"in_progress"` + - `type: "summary_text"` - - `"completed"` + The type of the object. Always `summary_text`. - - `"incomplete"` + - `"summary_text"` - - `type: "tool_search_call"` + - `type: "reasoning"` - The type of the item. Always `tool_search_call`. + The type of the object. Always `reasoning`. - - `"tool_search_call"` + - `"reasoning"` - `agent: optional object { agent_name }` @@ -117022,31 +115257,29 @@ 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 }` + - `content: optional array of object { text, type }` - - `id: string` + Reasoning text content. - The unique ID of the tool search output item. + - `text: string` - - `call_id: string` + The reasoning text from the model. - The unique ID of the tool search call generated by the model. + - `type: "reasoning_text"` - - `execution: "server" or "client"` + The type of the reasoning text. Always `reasoning_text`. - Whether tool search was executed by the server or by the client. + - `"reasoning_text"` - - `"server"` + - `encrypted_content: optional string` - - `"client"` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - - `status: "in_progress" or "completed" or "incomplete"` + - `status: optional "in_progress" or "completed" or "incomplete"` - The status of the tool search output item that was recorded. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `"in_progress"` @@ -117054,1021 +115287,986 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"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` + - `Compaction object { encrypted_content, type, id, agent }` - The loaded tool definitions returned by tool search. + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). - - `Function object { name, parameters, strict, 5 more }` + - `encrypted_content: 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 encrypted content of the compaction summary. - - `name: string` + - `type: "compaction"` - The name of the function to call. + The type of the item. Always `compaction`. - - `parameters: map[unknown]` + - `"compaction"` - A JSON schema object describing the parameters of the function. + - `id: optional string` - - `strict: boolean` + The ID of the compaction item. - Whether strict parameter validation is enforced for this function tool. + - `agent: optional object { agent_name }` - - `type: "function"` + The agent that produced this item. - The type of the function tool. Always `function`. + - `agent_name: string` - - `"function"` + The canonical name of the agent that produced this item. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `ImageGenerationCall object { id, result, status, 2 more }` - The tool invocation context(s). + An image generation request made by the model. - - `"direct"` + - `id: string` - - `"programmatic"` + The unique ID of the image generation call. - - `defer_loading: optional boolean` + - `result: string` - Whether this function is deferred and loaded via tool search. + The generated image encoded in base64. - - `description: optional string` + - `status: "in_progress" or "completed" or "generating" or "failed"` - A description of the function. Used by the model to determine whether or not to call the function. + The status of the image generation call. - - `output_schema: optional map[unknown]` + - `"in_progress"` - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `"completed"` - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + - `"generating"` - 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). + - `"failed"` - - `type: "file_search"` + - `type: "image_generation_call"` - The type of the file search tool. Always `file_search`. + The type of the image generation call. Always `image_generation_call`. - - `"file_search"` + - `"image_generation_call"` - - `vector_store_ids: array of string` + - `agent: optional object { agent_name }` - The IDs of the vector stores to search. + The agent that produced this item. - - `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 }` + - `CodeInterpreterCall object { id, code, container_id, 4 more }` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + A tool call to run code. - - `key: string` + - `id: string` - The key to compare against the value. + The unique ID of the code interpreter tool call. - - `type: "eq" or "ne" or "gt" or 5 more` + - `code: string` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The code to run, or null if not available. - - `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 + - `container_id: string` - - `"eq"` + The ID of the container used to run the code. - - `"ne"` + - `outputs: array of object { logs, type } or object { type, url }` - - `"gt"` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `"gte"` + - `Logs object { logs, type }` - - `"lt"` + The logs output from the code interpreter. - - `"lte"` + - `logs: string` - - `"in"` + The logs output from the code interpreter. - - `"nin"` + - `type: "logs"` - - `value: string or number or boolean or array of string or number` + The type of the output. Always `logs`. - The value to compare against the attribute key; supports string, number, or boolean types. + - `"logs"` - - `string` + - `Image object { type, url }` - - `number` + The image output from the code interpreter. - - `boolean` + - `type: "image"` - - `array of string or number` + The type of the output. Always `image`. - - `string` + - `"image"` - - `number` + - `url: string` - - `CompoundFilter object { filters, type }` + The URL of the image output from the code interpreter. - Combine multiple filters using `and` or `or`. + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - - `filters: array of object { key, type, value } or unknown` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `"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` + - `"interpreting"` - The key to compare against the value. + - `"failed"` - - `type: "eq" or "ne" or "gt" or 5 more` + - `type: "code_interpreter_call"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The type of the code interpreter tool call. Always `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 + - `"code_interpreter_call"` - - `"eq"` + - `agent: optional object { agent_name }` - - `"ne"` + The agent that produced this item. - - `"gt"` + - `agent_name: string` - - `"gte"` + The canonical name of the agent that produced this item. - - `"lt"` + - `LocalShellCall object { id, action, call_id, 3 more }` - - `"lte"` + A tool call to run a command on the local shell. - - `"in"` + - `id: string` - - `"nin"` + The unique ID of the local shell call. - - `value: string or number or boolean or array of string or number` + - `action: object { command, env, type, 3 more }` - The value to compare against the attribute key; supports string, number, or boolean types. + Execute a shell command on the server. - - `string` + - `command: array of string` - - `number` + The command to run. - - `boolean` + - `env: map[string]` - - `array of string or number` + Environment variables to set for the command. - - `string` + - `type: "exec"` - - `number` + The type of the local shell action. Always `exec`. - - `unknown` + - `"exec"` - - `type: "and" or "or"` + - `timeout_ms: optional number` - Type of operation: `and` or `or`. + Optional timeout in milliseconds for the command. - - `"and"` + - `user: optional string` - - `"or"` + Optional user to run the command as. - - `max_num_results: optional number` + - `working_directory: optional string` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + Optional working directory to run the command in. - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `call_id: string` - Ranking options for search. + The unique ID of the local shell tool call generated by the model. - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `status: "in_progress" or "completed" or "incomplete"` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + The status of the local shell call. - - `embedding_weight: number` + - `"in_progress"` - 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. + - `type: "local_shell_call"` - - `ranker: optional "auto" or "default-2024-11-15"` + The type of the local shell call. Always `local_shell_call`. - The ranker to use for the file search. + - `"local_shell_call"` - - `"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 }` + - `LocalShellCallOutput object { id, output, type, 2 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 local shell tool call. - - `type: "computer"` + - `id: string` - The type of the computer tool. Always `computer`. + The unique ID of the local shell tool call generated by the model. - - `"computer"` + - `output: string` - - `ComputerUsePreview object { display_height, display_width, environment, type }` + A JSON string of the output of the 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). + - `type: "local_shell_call_output"` - - `display_height: number` + The type of the local shell tool call output. Always `local_shell_call_output`. - The height of the computer display. + - `"local_shell_call_output"` - - `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"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"mac"` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `"linux"` + - `"in_progress"` - - `"ubuntu"` + - `"completed"` - - `"browser"` + - `"incomplete"` - - `type: "computer_use_preview"` + - `ShellCall object { action, call_id, type, 5 more }` - The type of the computer use tool. Always `computer_use_preview`. + A tool representing a request to execute one or more shell commands. - - `"computer_use_preview"` + - `action: object { commands, max_output_length, timeout_ms }` - - `WebSearch object { type, filters, search_context_size, user_location }` + The shell commands and limits that describe how to run the tool call. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `commands: array of string` - - `type: "web_search" or "web_search_2025_08_26"` + Ordered shell commands for the execution environment to run. - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `max_output_length: optional number` - - `"web_search"` + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - - `"web_search_2025_08_26"` + - `timeout_ms: optional number` - - `filters: optional object { allowed_domains }` + Maximum wall-clock time in milliseconds to allow the shell commands to run. - 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. + - `type: "shell_call"` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + The type of the item. Always `shell_call`. - - `search_context_size: optional "low" or "medium" or "high"` + - `"shell_call"` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `id: optional string` - - `"low"` + The unique ID of the shell tool call. Populated when this item is returned via API. - - `"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` + - `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` - - `type: optional "approximate"` + The call ID of the program item that produced this tool call. - The type of location approximation. Always `approximate`. + - `type: "program"` - - `"approximate"` + The caller type. Always `program`. - - `Mcp object { server_label, type, allowed_callers, 9 more }` + - `"program"` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `environment: optional BetaLocalEnvironment or BetaContainerReference` - - `server_label: string` + The environment to execute the shell commands in. - A label for this MCP server, used to identify it in tool calls. + - `BetaLocalEnvironment object { type, skills }` - - `type: "mcp"` + - `BetaContainerReference object { container_id, type }` - The type of the MCP tool. Always `mcp`. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"mcp"` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"in_progress"` - The tool invocation context(s). + - `"completed"` - - `"direct"` + - `"incomplete"` - - `"programmatic"` + - `ShellCallOutput object { call_id, output, type, 5 more }` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + The streamed output items emitted by a shell tool call. - List of allowed tool names or a filter object. + - `call_id: string` - - `McpAllowedTools = array of string` + The unique ID of the shell tool call generated by the model. - A string array of allowed tool names + - `output: array of BetaResponseFunctionShellCallOutputContent` - - `McpToolFilter object { read_only, tool_names }` + Captured chunks of stdout and stderr output, along with their associated outcomes. - A filter object to specify which tools are allowed. + - `outcome: object { type } or object { exit_code, type }` - - `read_only: optional boolean` + The exit or timeout outcome associated with this shell call. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `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](https://platform.openai.com/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` + The exit code returned by the shell process. - - `"connector_dropbox"` + - `type: "exit"` - - `"connector_gmail"` + The outcome type. Always `exit`. - - `"connector_googlecalendar"` + - `"exit"` - - `"connector_googledrive"` + - `stderr: string` - - `"connector_microsoftteams"` + Captured stderr output for the shell call. - - `"connector_outlookcalendar"` + - `stdout: string` - - `"connector_outlookemail"` + Captured stdout output for the shell call. - - `"connector_sharepoint"` + - `type: "shell_call_output"` - - `defer_loading: optional boolean` + The type of the item. Always `shell_call_output`. - Whether this MCP tool is deferred and discovered via tool search. + - `"shell_call_output"` - - `headers: optional map[string]` + - `id: optional string` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + The unique ID of the shell tool call output. Populated when this item is returned via API. - - `require_approval: optional object { always, never } or "always" or "never"` + - `agent: optional object { agent_name }` - Specify which of the MCP server's tools require approval. + The agent that produced this item. - - `McpToolApprovalFilter object { always, never }` + - `agent_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 canonical name of the agent that produced this item. - - `always: optional object { read_only, tool_names }` + - `caller: optional object { type } or object { caller_id, type }` - A filter object to specify which tools are allowed. + The execution context that produced this tool call. - - `read_only: optional boolean` + - `Direct object { type }` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `type: "direct"` - - `tool_names: optional array of string` + The caller type. Always `direct`. - List of allowed tool names. + - `"direct"` - - `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` + The caller type. Always `program`. - List of allowed tool names. + - `"program"` - - `McpToolApprovalSetting = "always" or "never"` + - `max_output_length: optional number` - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + The maximum number of UTF-8 characters captured for this shell call's combined output. - - `"always"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"never"` + The status of the shell call output. - - `server_description: optional string` + - `"in_progress"` - Optional description of the MCP server, used to provide more context. + - `"completed"` - - `server_url: optional string` + - `"incomplete"` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `ApplyPatchCall object { call_id, operation, status, 4 more }` - - `tunnel_id: optional string` + A tool call representing a request to create, delete, or update files using diff patches. - 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 }` + The specific create, delete, or update instruction for the apply_patch 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. + - `CreateFile object { diff, path, type }` - - `string` + Instruction for creating a new file via the apply_patch tool. - The container ID. + - `diff: string` - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + Unified diff content to apply when creating the file. - 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 relative to the workspace root. - Always `auto`. + - `type: "create_file"` - - `"auto"` + The operation type. Always `create_file`. - - `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 for deleting an existing file via the apply_patch tool. - The memory limit for the code interpreter container. + - `path: string` - - `"1g"` + Path of the file to delete relative to the workspace root. - - `"4g"` + - `type: "delete_file"` - - `"16g"` + The operation type. Always `delete_file`. - - `"64g"` + - `"delete_file"` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `UpdateFile object { diff, path, type }` - Network access policy for the container. + Instruction for updating an existing file via the apply_patch tool. - - `BetaContainerNetworkPolicyDisabled object { type }` + - `diff: string` - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + Unified diff content to apply to the existing file. - - `type: "code_interpreter"` + - `path: string` - The type of the code interpreter tool. Always `code_interpreter`. + Path of the file to update relative to the workspace root. - - `"code_interpreter"` + - `type: "update_file"` - - `allowed_callers: optional array of "direct" or "programmatic"` + The operation type. Always `update_file`. - 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. + - `id: optional string` - - `type: "image_generation"` + The unique ID of the apply patch tool call. 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"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + The caller type. Always `direct`. - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + - `"direct"` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `Program object { caller_id, type }` - - `"transparent"` + - `caller_id: string` - - `"opaque"` + The call ID of the program item that produced this tool call. - - `"auto"` + - `type: "program"` - - `input_fidelity: optional "high" or "low"` + The caller type. Always `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`. + - `"program"` - - `"high"` + - `ApplyPatchCallOutput object { call_id, status, type, 4 more }` - - `"low"` + The streamed output emitted by an apply patch tool call. - - `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-2" or 3 more` + - `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-2" or 3 more` + - `id: optional string` - The image generation model to use. Default: `gpt-image-1`. + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `"gpt-image-1"` + - `agent: optional object { agent_name }` - - `"gpt-image-1-mini"` + The agent that produced this item. - - `"gpt-image-2"` + - `agent_name: string` - - `"gpt-image-2-2026-04-21"` + The canonical name of the agent that produced this item. - - `"gpt-image-1.5"` + - `caller: optional object { type } or object { caller_id, type }` - - `"chatgpt-image-latest"` + The execution context that produced this tool call. - - `moderation: optional "auto" or "low"` + - `Direct object { type }` - Moderation level for the generated image. Default: `auto`. + - `type: "direct"` - - `"auto"` + The caller type. Always `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"` + The caller type. Always `program`. - - `"webp"` + - `"program"` - - `"jpeg"` + - `output: optional string` - - `partial_images: optional number` + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `McpListTools object { id, server_label, tools, 3 more }` - - `quality: optional "low" or "medium" or "high" or "auto"` + A list of tools available on an MCP server. - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `id: string` - - `"low"` + The unique ID of the list. - - `"medium"` + - `server_label: string` - - `"high"` + The label of the MCP server. - - `"auto"` + - `tools: array of object { input_schema, name, annotations, description }` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + The tools available on the server. - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `input_schema: unknown` - - `string` + The JSON schema describing the tool's input. - - `"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. - - `"1024x1024"` + - `annotations: optional unknown` - - `"1024x1536"` + Additional annotations about the tool. - - `"1536x1024"` + - `description: optional string` - - `"auto"` + The description of the tool. - - `LocalShell object { type }` + - `type: "mcp_list_tools"` - A tool that allows the model to execute shell commands in a local environment. + The type of the item. Always `mcp_list_tools`. - - `type: "local_shell"` + - `"mcp_list_tools"` - 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"` + - `error: optional string` - The type of the shell tool. Always `shell`. + Error message if the server could not list tools. - - `"shell"` + - `McpApprovalRequest object { id, arguments, name, 3 more }` - - `allowed_callers: optional array of "direct" or "programmatic"` + A request for human approval of a tool invocation. - The tool invocation context(s). + - `id: string` - - `"direct"` + The unique ID of the approval request. - - `"programmatic"` + - `arguments: string` - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + A JSON string of arguments for the tool. - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `name: string` - - `BetaLocalEnvironment object { type, skills }` + The name of the tool to run. - - `BetaContainerReference object { container_id, type }` + - `server_label: string` - - `Custom object { name, type, allowed_callers, 3 more }` + The label of the MCP server making the request. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `type: "mcp_approval_request"` - - `name: string` + The type of the item. Always `mcp_approval_request`. - The name of the custom tool, used to identify it in tool calls. + - `"mcp_approval_request"` - - `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). + - `McpApprovalResponse object { approval_request_id, approve, type, 3 more }` - - `"direct"` + A response to an MCP approval request. - - `"programmatic"` + - `approval_request_id: string` - - `defer_loading: optional boolean` + The ID of the approval request being answered. - Whether this tool should be deferred and discovered via tool search. + - `approve: boolean` - - `description: optional string` + Whether the request was approved. - Optional description of the custom tool, used to provide more context. + - `type: "mcp_approval_response"` - - `format: optional object { type } or object { definition, syntax, type }` + The type of the item. Always `mcp_approval_response`. - The input format for the custom tool. Default is unconstrained text. + - `"mcp_approval_response"` - - `Text object { type }` + - `id: optional string` - Unconstrained free-form text. + The unique ID of the approval response - - `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. + - `reason: optional string` - - `definition: string` + Optional reason for the decision. - The grammar definition. + - `McpCall object { id, arguments, name, 7 more }` - - `syntax: "lark" or "regex"` + An invocation of a tool on an MCP server. - The syntax of the grammar definition. One of `lark` or `regex`. + - `id: string` - - `"lark"` + The unique ID of the tool call. - - `"regex"` + - `arguments: string` - - `type: "grammar"` + A JSON string of the arguments passed to the tool. - Grammar format. Always `grammar`. + - `name: string` - - `"grammar"` + The name of the tool that was run. - - `Namespace object { description, name, tools, type }` + - `server_label: string` - Groups function/custom tools under a shared namespace. + The label of the MCP server running the tool. - - `description: string` + - `type: "mcp_call"` - A description of the namespace shown to the model. + The type of the item. Always `mcp_call`. - - `name: string` + - `"mcp_call"` - 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` + - `approval_request_id: optional string` - - `type: "function"` + 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. - - `"function"` + - `error: optional string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The error from the tool call, if any. - The tool invocation context(s). + - `output: optional string` - - `"direct"` + The output from the tool call. - - `"programmatic"` + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - - `defer_loading: optional boolean` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - Whether this function should be deferred and discovered via tool search. + - `"in_progress"` - - `description: optional string` + - `"completed"` - - `output_schema: optional map[unknown]` + - `"incomplete"` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `"calling"` - - `parameters: optional unknown` + - `"failed"` - - `strict: optional boolean` + - `CustomToolCallOutput object { call_id, output, type, 3 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. + The output of a custom tool call from your code, being sent back to the model. - - `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](https://platform.openai.com/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. + - `type: "custom_tool_call_output"` - - `format: optional object { type } or object { definition, syntax, type }` + The type of the custom tool call output. Always `custom_tool_call_output`. - The input format for the custom tool. Default is unconstrained text. + - `"custom_tool_call_output"` - - `Text object { type }` + - `id: optional string` - Unconstrained free-form text. + The unique ID of the custom tool call output in the OpenAI platform. - - `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. + - `caller: optional object { type } or object { caller_id, type }` - - `definition: string` + The execution context that produced this tool call. - The grammar definition. + - `Direct object { type }` - - `syntax: "lark" or "regex"` + - `type: "direct"` - The syntax of the grammar definition. One of `lark` or `regex`. + The caller type. Always `direct`. - - `"lark"` + - `"direct"` - - `"regex"` + - `Program object { caller_id, type }` - - `type: "grammar"` + - `caller_id: string` - Grammar format. Always `grammar`. + The call ID of the program item that produced this tool call. - - `"grammar"` + - `type: "program"` - - `type: "namespace"` + The caller type. Always `program`. - The type of the tool. Always `namespace`. + - `"program"` - - `"namespace"` + - `CustomToolCall object { call_id, input, name, 5 more }` - - `ToolSearch object { type, description, execution, parameters }` + A call to a custom tool created by the model. - Hosted or BYOT tool search configuration for deferred tools. + - `call_id: string` - - `type: "tool_search"` + An identifier used to map this custom tool call to a tool call output. - The type of the tool. Always `tool_search`. + - `input: string` - - `"tool_search"` + The input for the custom tool call generated by the model. - - `description: optional string` + - `name: string` - Description shown to the model for a client-executed tool search tool. + The name of the custom tool being called. - - `execution: optional "server" or "client"` + - `type: "custom_tool_call"` - Whether tool search is executed by the server or by the client. + The type of the custom tool call. Always `custom_tool_call`. - - `"server"` + - `"custom_tool_call"` - - `"client"` + - `id: optional string` - - `parameters: optional unknown` + The unique ID of the custom tool call in the OpenAI platform. - 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`. + - `caller: optional object { type } or object { caller_id, type }` - - `"web_search_preview"` + The execution context that produced this tool call. - - `"web_search_preview_2025_03_11"` + - `Direct object { type }` - - `search_content_types: optional array of "text" or "image"` + - `type: "direct"` - - `"text"` + - `"direct"` - - `"image"` + - `Program object { caller_id, type }` - - `search_context_size: optional "low" or "medium" or "high"` + - `caller_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 call ID of the program item that produced this tool call. - - `"low"` + - `type: "program"` - - `"medium"` + - `"program"` - - `"high"` + - `namespace: optional string` - - `user_location: optional object { type, city, country, 2 more }` + 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 user's location. + The canonical name of the agent that produced this item. - - `type: "approximate"` + - `ItemReference object { id, agent, type }` - The type of location approximation. Always `approximate`. + An internal identifier for an item to reference. - - `"approximate"` + - `id: string` - - `city: optional string` + The ID of the item to reference. - 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`. + - `type: optional "item_reference"` - - `timezone: optional string` + The type of item to reference. Always `item_reference`. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `"item_reference"` - - `ApplyPatch object { type, allowed_callers }` + - `Program object { id, call_id, code, 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 item. - The type of the tool. Always `apply_patch`. + - `call_id: string` - - `"apply_patch"` + The stable call ID of the program item. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `code: string` - The tool invocation context(s). + The JavaScript source executed by programmatic tool calling. - - `"direct"` + - `fingerprint: string` - - `"programmatic"` + Opaque program replay fingerprint that must be round-tripped. - - `type: "tool_search_output"` + - `type: "program"` - The type of the item. Always `tool_search_output`. + The item type. Always `program`. - - `"tool_search_output"` + - `"program"` - `agent: optional object { agent_name }` @@ -118078,1077 +116276,1079 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `created_by: optional string` + - `ProgramOutput object { id, call_id, result, 3 more }` - The identifier of the actor that created the item. + - `id: string` - - `AdditionalTools object { id, role, tools, 2 more }` + The unique ID of this program output item. - - `id: string` + - `call_id: string` - The unique ID of the additional tools item. + The call ID of the program item. - - `role: "unknown" or "user" or "assistant" or 5 more` + - `result: string` - The role that provided the additional tools. + The result produced by the program item. - - `"unknown"` + - `status: "completed" or "incomplete"` - - `"user"` + The terminal status of the program output. - - `"assistant"` + - `"completed"` - - `"system"` + - `"incomplete"` - - `"critic"` + - `type: "program_output"` - - `"discriminator"` + The item type. Always `program_output`. - - `"developer"` + - `"program_output"` - - `"tool"` + - `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. - The additional tool definitions 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). + - `metadata: map[string]` - - `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 function to call. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `parameters: map[unknown]` + - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` - A JSON schema object describing the parameters of the function. + 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. - - `strict: boolean` + - `"gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more` - Whether strict parameter validation is enforced for this function tool. + 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: "function"` + - `"gpt-5.6-sol"` - The type of the function tool. Always `function`. + - `"gpt-5.6-terra"` - - `"function"` + - `"gpt-5.6-luna"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"gpt-5.4"` - The tool invocation context(s). + - `"gpt-5.4-mini"` - - `"direct"` + - `"gpt-5.4-nano"` - - `"programmatic"` + - `"gpt-5.4-mini-2026-03-17"` - - `defer_loading: optional boolean` + - `"gpt-5.4-nano-2026-03-17"` - Whether this function is deferred and loaded via tool search. + - `"gpt-5.3-chat-latest"` - - `description: optional string` + - `"gpt-5.2"` - A description of the function. Used by the model to determine whether or not to call the function. + - `"gpt-5.2-2025-12-11"` - - `output_schema: optional map[unknown]` + - `"gpt-5.2-chat-latest"` - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `"gpt-5.2-pro"` - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + - `"gpt-5.2-pro-2025-12-11"` - 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-5.1"` - - `type: "file_search"` + - `"gpt-5.1-2025-11-13"` - The type of the file search tool. Always `file_search`. + - `"gpt-5.1-codex"` - - `"file_search"` + - `"gpt-5.1-mini"` - - `vector_store_ids: array of string` + - `"gpt-5.1-chat-latest"` - The IDs of the vector stores to search. + - `"gpt-5"` - - `filters: optional object { key, type, value } or object { filters, type }` + - `"gpt-5-mini"` - A filter to apply. + - `"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"` - - `CompoundFilter object { filters, type }` + - `"gpt-4o-2024-11-20"` - Combine multiple filters using `and` or `or`. + - `"gpt-4o-2024-08-06"` - - `filters: array of object { key, type, value } or unknown` + - `"gpt-4o-2024-05-13"` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `"gpt-4o-audio-preview"` - - `ComparisonFilter object { key, type, value }` + - `"gpt-4o-audio-preview-2024-10-01"` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `"gpt-4o-audio-preview-2024-12-17"` - - `key: string` + - `"gpt-4o-audio-preview-2025-06-03"` - The key to compare against the value. + - `"gpt-4o-mini-audio-preview"` - - `type: "eq" or "ne" or "gt" or 5 more` + - `"gpt-4o-mini-audio-preview-2024-12-17"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `"gpt-4o-search-preview"` - - `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-4o-mini-search-preview"` - - `"eq"` + - `"gpt-4o-search-preview-2025-03-11"` - - `"ne"` + - `"gpt-4o-mini-search-preview-2025-03-11"` - - `"gt"` + - `"chatgpt-4o-latest"` - - `"gte"` + - `"codex-mini-latest"` - - `"lt"` + - `"gpt-4o-mini"` - - `"lte"` + - `"gpt-4o-mini-2024-07-18"` - - `"in"` + - `"gpt-4-turbo"` - - `"nin"` + - `"gpt-4-turbo-2024-04-09"` - - `value: string or number or boolean or array of string or number` + - `"gpt-4-0125-preview"` - The value to compare against the attribute key; supports string, number, or boolean types. + - `"gpt-4-turbo-preview"` - - `string` + - `"gpt-4-1106-preview"` - - `number` + - `"gpt-4-vision-preview"` - - `boolean` + - `"gpt-4"` - - `array of string or number` + - `"gpt-4-0314"` - - `string` + - `"gpt-4-0613"` - - `number` + - `"gpt-4-32k"` - - `unknown` + - `"gpt-4-32k-0314"` - - `type: "and" or "or"` + - `"gpt-4-32k-0613"` - Type of operation: `and` or `or`. + - `"gpt-3.5-turbo"` - - `"and"` + - `"gpt-3.5-turbo-16k"` - - `"or"` + - `"gpt-3.5-turbo-0301"` - - `max_num_results: optional number` + - `"gpt-3.5-turbo-0613"` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `"gpt-3.5-turbo-1106"` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `"gpt-3.5-turbo-0125"` - Ranking options for search. + - `"gpt-3.5-turbo-16k-0613"` - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `"o1-pro"` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `"o1-pro-2025-03-19"` - - `embedding_weight: number` + - `"o3-pro"` - The weight of the embedding in the reciprocal ranking fusion. + - `"o3-pro-2025-06-10"` - - `text_weight: number` + - `"o3-deep-research"` - The weight of the text in the reciprocal ranking fusion. + - `"o3-deep-research-2025-06-26"` - - `ranker: optional "auto" or "default-2024-11-15"` + - `"o4-mini-deep-research"` - The ranker to use for the file search. + - `"o4-mini-deep-research-2025-06-26"` - - `"auto"` + - `"computer-use-preview"` - - `"default-2024-11-15"` + - `"computer-use-preview-2025-03-11"` - - `score_threshold: optional number` + - `"gpt-5-codex"` - 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-5-pro"` - - `Computer object { type }` + - `"gpt-5-pro-2025-10-06"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `"gpt-5.1-codex-max"` - - `type: "computer"` + - `string` - The type of the computer tool. Always `computer`. + - `object: "response"` - - `"computer"` + The object type of this resource - always set to `response`. - - `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). + - `output: array of BetaResponseOutputItem` - - `display_height: number` + An array of content items generated by the model. - The height of the computer display. + - 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. - - `display_width: number` + - `BetaResponseOutputMessage object { id, content, role, 4 more }` - The width of the computer display. + An output message from the model. - - `environment: "windows" or "mac" or "linux" or 2 more` + - `FileSearchCall object { id, queries, status, 3 more }` - The type of computer environment to control. + The results of a file search tool call. See the + [file search guide](/docs/guides/tools-file-search) for more information. - - `"windows"` + - `id: string` - - `"mac"` + The unique ID of the file search tool call. - - `"linux"` + - `queries: array of string` - - `"ubuntu"` + The queries used to search for files. - - `"browser"` + - `status: "in_progress" or "searching" or "completed" or 2 more` - - `type: "computer_use_preview"` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - The type of the computer use tool. Always `computer_use_preview`. + - `"in_progress"` - - `"computer_use_preview"` + - `"searching"` - - `WebSearch object { type, filters, search_context_size, user_location }` + - `"completed"` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `"incomplete"` - - `type: "web_search" or "web_search_2025_08_26"` + - `"failed"` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `type: "file_search_call"` - - `"web_search"` + The type of the file search tool call. Always `file_search_call`. - - `"web_search_2025_08_26"` + - `"file_search_call"` - - `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"]` + - `results: optional array of object { attributes, file_id, filename, 2 more }` - - `search_context_size: optional "low" or "medium" or "high"` + The results of the file search 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. + - `attributes: optional map[string or number or boolean]` - - `"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. - - `"medium"` + - `string` - - `"high"` + - `number` - - `user_location: optional object { city, country, region, 2 more }` + - `boolean` - The approximate location of the user. + - `file_id: optional string` - - `city: optional string` + The unique ID of the file. - Free text input for the city of the user, e.g. `San Francisco`. + - `filename: optional string` - - `country: optional string` + The name of the file. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `score: optional number` - - `region: optional string` + The relevance score of the file - a value between 0 and 1. - Free text input for the region of the user, e.g. `California`. + - `text: optional string` - - `timezone: optional string` + The text that was retrieved from the file. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `FunctionCall object { arguments, call_id, name, 6 more }` - - `type: optional "approximate"` + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. - The type of location approximation. Always `approximate`. + - `arguments: string` - - `"approximate"` + A JSON string of the arguments to pass to the function. - - `Mcp object { server_label, type, allowed_callers, 9 more }` + - `call_id: string` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + The unique ID of the function tool call generated by the model. - - `server_label: string` + - `name: string` - A label for this MCP server, used to identify it in tool calls. + The name of the function to run. - - `type: "mcp"` + - `type: "function_call"` - The type of the MCP tool. Always `mcp`. + The type of the function tool call. Always `function_call`. - - `"mcp"` + - `"function_call"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `id: optional string` - The tool invocation context(s). + The unique ID of the function tool call. - - `"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` + - `"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. + - `Program object { caller_id, type }` - - `tool_names: optional array of string` + - `caller_id: string` - List of allowed tool names. + The call ID of the program item that produced this tool call. - - `authorization: optional string` + - `type: "program"` - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. + - `"program"` - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + - `namespace: 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + The namespace of the function to run. - 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 the 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"` + - `FunctionCallOutput object { id, call_id, output, 5 more }` - - `"connector_microsoftteams"` + - `id: string` - - `"connector_outlookcalendar"` + The unique ID of the function call tool output. - - `"connector_outlookemail"` + - `call_id: string` - - `"connector_sharepoint"` + The unique ID of the function tool call generated by the model. - - `defer_loading: optional boolean` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - Whether this MCP tool is deferred and discovered via tool search. + The output from the function call generated by your code. + Can be a string or an list of output content. - - `headers: optional map[string]` + - `StringOutput = string` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + A string of the output of the function call. - - `require_approval: optional object { always, never } or "always" or "never"` + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - Specify which of the MCP server's tools require approval. + Text, image, or file output of the function call. - - `McpToolApprovalFilter object { always, never }` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - 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 text input to the model. - - `always: optional object { read_only, tool_names }` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - A filter object to specify which tools are allowed. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `read_only: optional boolean` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + A file input to the model. - - `tool_names: optional array of string` + - `status: "in_progress" or "completed" or "incomplete"` - List of allowed tool names. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `never: optional object { read_only, tool_names }` + - `"in_progress"` - A filter object to specify which tools are allowed. + - `"completed"` - - `read_only: optional boolean` + - `"incomplete"` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `type: "function_call_output"` - - `tool_names: optional array of string` + The type of the function tool call output. Always `function_call_output`. - List of allowed tool names. + - `"function_call_output"` - - `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 }` + - `created_by: optional string` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + The identifier of the actor that created the item. - - `type: "auto"` + - `AgentMessage object { id, author, content, 3 more }` - Always `auto`. + - `id: string` - - `"auto"` + The unique ID of the agent message. - - `file_ids: optional array of string` + - `author: string` - An optional list of uploaded files to make available to your code. + The sending agent identity. - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` - The memory limit for the code interpreter container. + Encrypted content sent between agents. - - `"1g"` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `"4g"` + A text input to the model. - - `"16g"` + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - - `"64g"` + A text output from the model. - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `Text object { text, type }` - Network access policy for the container. + A text content. - - `BetaContainerNetworkPolicyDisabled object { type }` + - `text: string` - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `type: "text"` - - `type: "code_interpreter"` + - `"text"` - The type of the code interpreter tool. Always `code_interpreter`. + - `SummaryText object { text, type }` - - `"code_interpreter"` + A summary text from the model. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `text: string` - The tool invocation context(s). + A summary of the reasoning output from the model so far. - - `"direct"` + - `type: "summary_text"` - - `"programmatic"` + The type of the object. Always `summary_text`. - - `ProgrammaticToolCalling object { type }` + - `"summary_text"` - - `type: "programmatic_tool_calling"` + - `ReasoningText object { text, type }` - The type of the tool. Always `programmatic_tool_calling`. + Reasoning text from the model. - - `"programmatic_tool_calling"` + - `text: string` - - `ImageGeneration object { type, action, background, 9 more }` + The reasoning text from the model. - A tool that generates images using the GPT image models. + - `type: "reasoning_text"` - - `type: "image_generation"` + The type of the reasoning text. Always `reasoning_text`. - The type of the image generation tool. Always `image_generation`. + - `"reasoning_text"` - - `"image_generation"` + - `BetaResponseOutputRefusal object { refusal, type }` - - `action: optional "generate" or "edit" or "auto"` + A refusal from the model. - Whether to generate a new image or edit an existing image. Default: `auto`. + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `"generate"` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `"edit"` + - `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"` - - `background: optional "transparent" or "opaque" or "auto"` + - `"original"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + - `file_id: string` - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + The identifier of an uploaded file that contains the screenshot. - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `image_url: string` - - `"transparent"` + The URL of the screenshot image. - - `"opaque"` + - `type: "computer_screenshot"` - - `"auto"` + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `input_fidelity: optional "high" or "low"` + - `"computer_screenshot"` - Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + - `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. - - `"low"` + - `mode: "explicit"` - - `input_image_mask: optional object { file_id, image_url }` + The breakpoint mode. Always `explicit`. - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `"explicit"` - - `file_id: optional string` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - File ID for the mask image. + A file input to the model. - - `image_url: optional string` + - `EncryptedContent object { encrypted_content, type }` - Base64-encoded mask image. + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `encrypted_content: string` - The image generation model to use. Default: `gpt-image-1`. + Opaque encrypted content. - - `string` + - `type: "encrypted_content"` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + The type of the input item. Always `encrypted_content`. - The image generation model to use. Default: `gpt-image-1`. + - `"encrypted_content"` - - `"gpt-image-1"` + - `recipient: string` - - `"gpt-image-1-mini"` + The destination agent identity. - - `"gpt-image-2"` + - `type: "agent_message"` - - `"gpt-image-2-2026-04-21"` + The type of the item. Always `agent_message`. - - `"gpt-image-1.5"` + - `"agent_message"` - - `"chatgpt-image-latest"` + - `agent: optional object { agent_name }` - - `moderation: optional "auto" or "low"` + The agent that produced this item. - Moderation level for the generated image. Default: `auto`. + - `agent_name: string` - - `"auto"` + The canonical name of the agent that produced this item. - - `"low"` + - `MultiAgentCall object { id, action, arguments, 3 more }` - - `output_compression: optional number` + - `id: string` - Compression level for the output image. Default: 100. + The unique ID of the multi-agent call item. - - `output_format: optional "png" or "webp" or "jpeg"` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + The multi-agent action to execute. - - `"png"` + - `"spawn_agent"` - - `"webp"` + - `"interrupt_agent"` - - `"jpeg"` + - `"list_agents"` - - `partial_images: optional number` + - `"send_message"` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `"followup_task"` - - `quality: optional "low" or "medium" or "high" or "auto"` + - `"wait_agent"` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `arguments: string` - - `"low"` + The JSON string of arguments generated for the action. - - `"medium"` + - `call_id: string` - - `"high"` + The unique ID linking this call to its output. - - `"auto"` + - `type: "multi_agent_call"` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + The type of the multi-agent call. Always `multi_agent_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`. + - `"multi_agent_call"` - - `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"` + - `MultiAgentCallOutput object { id, action, call_id, 3 more }` - - `"1536x1024"` + - `id: string` - - `"auto"` + The unique ID of the multi-agent call output item. - - `LocalShell object { type }` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - A tool that allows the model to execute shell commands in a local environment. + The multi-agent action that produced this result. - - `type: "local_shell"` + - `"spawn_agent"` - The type of the local shell tool. Always `local_shell`. + - `"interrupt_agent"` - - `"local_shell"` + - `"list_agents"` - - `Shell object { type, allowed_callers, environment }` + - `"send_message"` - A tool that allows the model to execute shell commands. + - `"followup_task"` - - `type: "shell"` + - `"wait_agent"` - The type of the shell tool. Always `shell`. + - `call_id: string` - - `"shell"` + The unique ID of the multi-agent call. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `output: array of BetaResponseOutputText` - The tool invocation context(s). + Text output returned by the multi-agent action. - - `"direct"` + - `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 }` - - `"programmatic"` + The annotations of the text output. - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `text: string` - - `BetaLocalEnvironment object { type, skills }` + The text output from the model. - - `BetaContainerReference object { container_id, type }` + - `type: "output_text"` - - `Custom object { name, type, allowed_callers, 3 more }` + The type of the output text. Always `output_text`. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `type: "multi_agent_call_output"` - - `name: string` + The type of the multi-agent result. Always `multi_agent_call_output`. - The name of the custom tool, used to identify it in tool calls. + - `"multi_agent_call_output"` - - `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). + - `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"` + - `id: string` - - `defer_loading: optional boolean` + The unique ID of the web search tool call. - Whether this tool should be deferred and discovered via tool search. + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - - `description: 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). - Optional description of the custom tool, used to provide more context. + - `Search object { type, queries, query, sources }` - - `format: optional object { type } or object { definition, syntax, type }` + Action type "search" - Performs a web search query. - The input format for the custom tool. Default is unconstrained text. + - `type: "search"` - - `Text object { type }` + The action type. - Unconstrained free-form text. + - `"search"` - - `type: "text"` + - `queries: optional array of string` - Unconstrained text format. Always `text`. + The search queries. - - `"text"` + - `query: optional string` - - `Grammar object { definition, syntax, type }` + The search query. - A grammar defined by the user. + - `sources: optional array of object { type, url }` - - `definition: string` + The sources used in the search. - The grammar definition. + - `type: "url"` - - `syntax: "lark" or "regex"` + The type of source. Always `url`. - The syntax of the grammar definition. One of `lark` or `regex`. + - `"url"` - - `"lark"` + - `url: string` - - `"regex"` + The URL of the source. - - `type: "grammar"` + - `OpenPage object { type, url }` - Grammar format. Always `grammar`. + Action type "open_page" - Opens a specific URL from search results. - - `"grammar"` + - `type: "open_page"` - - `Namespace object { description, name, tools, type }` + The action type. - Groups function/custom tools under a shared namespace. + - `"open_page"` - - `description: string` + - `url: optional string` - A description of the namespace shown to the model. + The URL opened by the model. - - `name: string` + - `FindInPage object { pattern, type, url }` - The namespace name used in tool calls (for example, `crm`). + Action type "find_in_page": Searches for a pattern within a loaded page. - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + - `pattern: string` - The function/custom tools available inside this namespace. + The pattern or text to search for within the page. - - `Function object { name, type, allowed_callers, 5 more }` + - `type: "find_in_page"` - - `name: string` + The action type. - - `type: "function"` + - `"find_in_page"` - - `"function"` + - `url: string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The URL of the page searched for the pattern. - The tool invocation context(s). + - `status: "in_progress" or "searching" or "completed" or "failed"` - - `"direct"` + The status of the web search tool call. - - `"programmatic"` + - `"in_progress"` - - `defer_loading: optional boolean` + - `"searching"` - Whether this function should be deferred and discovered via tool search. + - `"completed"` - - `description: optional string` + - `"failed"` - - `output_schema: optional map[unknown]` + - `type: "web_search_call"` - 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 web search tool call. Always `web_search_call`. - - `parameters: optional unknown` + - `"web_search_call"` - - `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](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The canonical name of the agent that produced this item. - - `name: string` + - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` - The name of the custom tool, used to identify it in tool calls. + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - - `type: "custom"` + - `id: string` - The type of the custom tool. Always `custom`. + The unique ID of the computer call. - - `"custom"` + - `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 tool should be deferred and discovered via tool search. + - `code: optional string` - - `description: optional string` + The type of the pending safety check. - Optional description of the custom tool, used to provide more context. + - `message: optional string` - - `format: optional object { type } or object { definition, syntax, type }` + Details about the pending safety check. - The input format for the custom tool. Default is unconstrained text. + - `status: "in_progress" or "completed" or "incomplete"` - - `Text object { type }` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Unconstrained free-form text. + - `"in_progress"` - - `type: "text"` + - `"completed"` - Unconstrained text format. Always `text`. + - `"incomplete"` - - `"text"` + - `type: "computer_call"` - - `Grammar object { definition, syntax, type }` + The type of the computer call. Always `computer_call`. - A grammar defined by the user. + - `"computer_call"` - - `definition: string` + - `action: optional BetaComputerAction` - The grammar definition. + A click action. - - `syntax: "lark" or "regex"` + - `actions: optional BetaComputerActionList` - The syntax of the grammar definition. One of `lark` or `regex`. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `"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"` + - `ComputerCallOutput object { id, call_id, output, 5 more }` - - `type: "namespace"` + - `id: string` - The type of the tool. Always `namespace`. + The unique ID of the computer call tool output. - - `"namespace"` + - `call_id: string` - - `ToolSearch object { type, description, execution, parameters }` + The ID of the computer tool call that produced the output. - Hosted or BYOT tool search configuration for deferred tools. + - `output: BetaResponseComputerToolCallOutputScreenshot` - - `type: "tool_search"` + A computer screenshot image used with the computer use tool. - The type of the tool. Always `tool_search`. + - `status: "completed" or "incomplete" or "failed" or "in_progress"` - - `"tool_search"` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `description: optional string` + - `"completed"` - Description shown to the model for a client-executed tool search tool. + - `"incomplete"` - - `execution: optional "server" or "client"` + - `"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 }` - Whether tool search is executed by the server or by the client. + The safety checks reported by the API that have been acknowledged by the + developer. - - `"server"` + - `id: string` - - `"client"` + The ID of the pending safety check. - - `parameters: optional unknown` + - `code: optional string` - Parameter schema for a client-executed tool search tool. + The type of the pending safety check. - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + - `message: optional string` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + Details about the pending safety check. - - `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"` + - `created_by: optional string` - - `"text"` + The identifier of the actor that created the item. - - `"image"` + - `Reasoning object { id, summary, type, 4 more }` - - `search_context_size: optional "low" or "medium" or "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). - 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 identifier of the reasoning content. - - `"medium"` + - `summary: array of object { text, type }` - - `"high"` + Reasoning summary content. - - `user_location: optional object { type, city, country, 2 more }` + - `text: string` - The user's location. + A summary of the reasoning output from the model so far. - - `type: "approximate"` + - `type: "summary_text"` - The type of location approximation. Always `approximate`. + The type of the object. Always `summary_text`. - - `"approximate"` + - `"summary_text"` - - `city: optional string` + - `type: "reasoning"` - Free text input for the city of the user, e.g. `San Francisco`. + The type of the object. Always `reasoning`. - - `country: optional string` + - `"reasoning"` - 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`. + - `content: optional array of object { text, type }` - - `ApplyPatch object { type, allowed_callers }` + Reasoning text content. - Allows the assistant to create, delete, or update files using unified diffs. + - `text: string` - - `type: "apply_patch"` + The reasoning text from the model. - The type of the tool. Always `apply_patch`. + - `type: "reasoning_text"` - - `"apply_patch"` + The type of the reasoning text. Always `reasoning_text`. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"reasoning_text"` - The tool invocation context(s). + - `encrypted_content: optional string` - - `"direct"` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - - `"programmatic"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `type: "additional_tools"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The type of the item. Always `additional_tools`. + - `"in_progress"` - - `"additional_tools"` + - `"completed"` - - `agent: optional object { agent_name }` + - `"incomplete"` - The agent that produced this item. + - `Program object { id, call_id, code, 3 more }` - - `agent_name: string` + - `id: string` - The canonical name of the agent that produced this item. + The unique ID of the program item. - - `Compaction object { id, encrypted_content, type, 2 more }` + - `call_id: string` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + The stable call ID of the program item. - - `id: string` + - `code: string` - The unique ID of the compaction item. + The JavaScript source executed by programmatic tool calling. - - `encrypted_content: string` + - `fingerprint: string` - The encrypted content that was produced by compaction. + Opaque program replay fingerprint that must be round-tripped. - - `type: "compaction"` + - `type: "program"` - The type of the item. Always `compaction`. + The type of the item. Always `program`. - - `"compaction"` + - `"program"` - `agent: optional object { agent_name }` @@ -119158,39 +117358,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 the 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 item. - `"completed"` - - `"generating"` - - - `"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 }` @@ -119200,58 +117394,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"` @@ -119259,1031 +117472,1046 @@ 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 { id, action, call_id, 6 more }` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - A tool call that executes one or more shell commands in a managed environment. + - `key: string` - - `id: string` + The key to compare against the value. - The unique ID of the shell tool call. Populated when this item is returned via API. + - `type: "eq" or "ne" or "gt" or 5 more` - - `action: object { commands, max_output_length, timeout_ms }` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The shell commands and limits that describe how to run the 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 - - `commands: array of string` + - `"eq"` - - `max_output_length: number` + - `"ne"` - Optional maximum number of characters to return from each command. + - `"gt"` - - `timeout_ms: number` + - `"gte"` - Optional timeout in milliseconds for the commands. + - `"lt"` - - `call_id: string` + - `"lte"` - The unique ID of the shell tool call generated by the model. + - `"in"` - - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` + - `"nin"` - Represents the use of a local environment to perform shell actions. + - `value: string or number or boolean or array of string or number` - - `BetaResponseLocalEnvironment object { type }` + The value to compare against the attribute key; supports string, number, or boolean types. - Represents the use of a local environment to perform shell actions. + - `string` - - `type: "local"` + - `number` - The environment type. Always `local`. + - `boolean` - - `"local"` + - `array of string or number` - - `BetaResponseContainerReference object { container_id, type }` + - `string` - Represents a container created with /v1/containers. + - `number` - - `container_id: string` + - `unknown` - - `type: "container_reference"` + - `type: "and" or "or"` - The environment type. Always `container_reference`. + Type of operation: `and` or `or`. - - `"container_reference"` + - `"and"` - - `status: "in_progress" or "completed" or "incomplete"` + - `"or"` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `max_num_results: optional number` - - `"in_progress"` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `"completed"` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `"incomplete"` + Ranking options for search. - - `type: "shell_call"` + - `hybrid_search: optional object { embedding_weight, text_weight }` - The type of the item. Always `shell_call`. + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `"shell_call"` + - `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"` - - `caller: optional object { type } or object { caller_id, type }` + The ranker to use for the file search. - The execution context that produced this tool call. + - `"auto"` - - `Direct object { type }` + - `"default-2024-11-15"` - - `type: "direct"` + - `score_threshold: optional number` - - `"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. - - `Program object { caller_id, type }` + - `Computer object { type }` - - `caller_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 call ID of the program item that produced this tool call. + - `type: "computer"` - - `type: "program"` + The type of the computer tool. Always `computer`. - - `"program"` + - `"computer"` - - `created_by: optional string` + - `ComputerUsePreview object { display_height, display_width, environment, type }` - The ID of the entity that created 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). - - `ShellCallOutput object { id, call_id, max_output_length, 6 more }` + - `display_height: number` - The output of a shell tool call that was emitted. + The height of the computer display. - - `id: string` + - `display_width: number` - The unique ID of the shell call output. Populated when this item is returned via API. + The width of the computer display. - - `call_id: string` + - `environment: "windows" or "mac" or "linux" or 2 more` - The unique ID of the shell tool call generated by the model. + The type of computer environment to control. - - `max_output_length: number` + - `"windows"` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `"mac"` - - `output: array of object { outcome, stderr, stdout, created_by }` + - `"linux"` - An array of shell call output contents + - `"ubuntu"` - - `outcome: object { type } or object { exit_code, type }` + - `"browser"` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + - `type: "computer_use_preview"` - - `Timeout object { type }` + The type of the computer use tool. Always `computer_use_preview`. - Indicates that the shell call exceeded its configured time limit. + - `"computer_use_preview"` - - `type: "timeout"` + - `WebSearch object { type, filters, search_context_size, user_location }` - The outcome type. Always `timeout`. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - - `"timeout"` + - `type: "web_search" or "web_search_2025_08_26"` - - `Exit object { exit_code, type }` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - Indicates that the shell commands finished and returned an exit code. + - `"web_search"` - - `exit_code: number` + - `"web_search_2025_08_26"` - Exit code from the shell process. + - `filters: optional object { allowed_domains }` - - `type: "exit"` + Filters for the search. - The outcome type. Always `exit`. + - `allowed_domains: optional array of string` - - `"exit"` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `stderr: string` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - The standard error output that was captured. + - `search_context_size: optional "low" or "medium" or "high"` - - `stdout: string` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - The standard output that was captured. + - `"low"` - - `created_by: optional string` + - `"medium"` - The identifier of the actor that created the item. + - `"high"` - - `status: "in_progress" or "completed" or "incomplete"` + - `user_location: optional object { city, country, region, 2 more }` - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + The approximate location of the user. - - `"in_progress"` + - `city: optional string` - - `"completed"` + Free text input for the city of the user, e.g. `San Francisco`. - - `"incomplete"` + - `country: optional string` - - `type: "shell_call_output"` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The type of the shell call output. Always `shell_call_output`. + - `region: optional string` - - `"shell_call_output"` + Free text input for the region of the user, e.g. `California`. - - `agent: optional object { agent_name }` + - `timezone: optional string` - The agent that produced this item. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `agent_name: string` + - `type: optional "approximate"` - The canonical name of the agent that produced this item. + The type of location approximation. Always `approximate`. - - `caller: optional object { type } or object { caller_id, type }` + - `"approximate"` - The execution context that produced this tool call. + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `Direct object { type }` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - - `type: "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"` - - `"program"` + The tool invocation context(s). - - `created_by: optional string` + - `"direct"` - The identifier of the actor that created the item. + - `"programmatic"` - - `ApplyPatchCall object { id, call_id, operation, 5 more }` + - `allowed_tools: optional array of string or object { read_only, tool_names }` - A tool call that applies file diffs by creating, deleting, or updating files. + List of allowed tool names or a filter object. - - `id: string` + - `McpAllowedTools = array of string` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + A string array of allowed tool names - - `call_id: string` + - `McpToolFilter object { read_only, tool_names }` - The unique ID of the apply patch tool call generated by the model. + A filter object to specify which tools are allowed. - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + - `read_only: optional boolean` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + 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. - - `CreateFile object { diff, path, type }` + - `tool_names: optional array of string` - Instruction describing how to create a file via the apply_patch tool. + List of allowed tool names. - - `diff: string` + - `authorization: optional string` - Diff to apply. + 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. - - `path: string` + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - Path of the file to create. + 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: "create_file"` + Currently supported `connector_id` values are: - Create a new file with the provided diff. + - 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` - - `"create_file"` + - `"connector_dropbox"` - - `DeleteFile object { path, type }` + - `"connector_gmail"` - Instruction describing how to delete a file via the apply_patch tool. + - `"connector_googlecalendar"` - - `path: string` + - `"connector_googledrive"` - Path of the file to delete. + - `"connector_microsoftteams"` - - `type: "delete_file"` + - `"connector_outlookcalendar"` - Delete the specified file. + - `"connector_outlookemail"` - - `"delete_file"` + - `"connector_sharepoint"` - - `UpdateFile object { diff, path, type }` + - `defer_loading: optional boolean` - Instruction describing how to update a file via the apply_patch tool. + Whether this MCP tool is deferred and discovered via tool search. - - `diff: string` + - `headers: optional map[string]` - Diff to apply. + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `path: string` + - `require_approval: optional object { always, never } or "always" or "never"` - Path of the file to update. + Specify which of the MCP server's tools require approval. - - `type: "update_file"` + - `McpToolApprovalFilter object { always, never }` - Update an existing file with the provided diff. + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `"update_file"` + - `always: optional object { read_only, tool_names }` - - `status: "in_progress" or "completed"` + A filter object to specify which tools are allowed. - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `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` - - `type: "apply_patch_call"` + List of allowed tool names. - The type of the item. Always `apply_patch_call`. + - `never: optional object { read_only, tool_names }` - - `"apply_patch_call"` + 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 }` + - `McpToolApprovalSetting = "always" or "never"` - The execution context 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. - - `Direct object { type }` + - `"always"` - - `type: "direct"` + - `"never"` - - `"direct"` + - `server_description: optional string` - - `Program object { caller_id, type }` + Optional description of the MCP server, used to provide more context. - - `caller_id: string` + - `server_url: optional string` - The call ID of the program item that produced this tool call. + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `type: "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. - - `created_by: optional string` + - `CodeInterpreter object { container, type, allowed_callers }` - The ID of the entity that created this tool call. + A tool that runs Python code to help generate a response to a prompt. - - `ApplyPatchCallOutput object { id, call_id, status, 5 more }` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - The output emitted by an apply patch 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. - - `id: string` + - `string` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + The container ID. - - `call_id: string` + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - The unique ID of the apply patch tool call generated by the model. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `status: "completed" or "failed"` + - `type: "auto"` - The status of the apply patch tool call output. One of `completed` or `failed`. + Always `auto`. - - `"completed"` + - `"auto"` - - `"failed"` + - `file_ids: optional array of string` - - `type: "apply_patch_call_output"` + An optional list of uploaded files to make available to your code. - The type of the item. Always `apply_patch_call_output`. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `"apply_patch_call_output"` + The memory limit for the code interpreter container. - - `agent: optional object { agent_name }` + - `"1g"` - The agent that produced this item. + - `"4g"` - - `agent_name: string` + - `"16g"` - The canonical name of the agent that produced this item. + - `"64g"` - - `caller: optional object { type } or object { caller_id, type }` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - The execution context that produced this tool call. + Network access policy for the container. - - `Direct object { type }` + - `BetaContainerNetworkPolicyDisabled object { type }` - - `type: "direct"` + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `"direct"` + - `type: "code_interpreter"` - - `Program object { caller_id, type }` + The type of the code interpreter tool. Always `code_interpreter`. - - `caller_id: string` + - `"code_interpreter"` - 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 ID of the entity that created this tool call output. + - `ProgrammaticToolCalling object { type }` - - `output: optional string` + - `type: "programmatic_tool_calling"` - Optional textual output returned by the apply patch tool. + The type of the tool. Always `programmatic_tool_calling`. - - `McpCall object { id, arguments, name, 7 more }` + - `"programmatic_tool_calling"` - An invocation of a tool on an MCP server. + - `ImageGeneration object { type, action, background, 9 more }` - - `id: string` + A tool that generates images using the GPT image models. - The unique ID of the tool call. + - `type: "image_generation"` - - `arguments: string` + The type of the image generation tool. Always `image_generation`. - A JSON string of the arguments passed to the tool. + - `"image_generation"` - - `name: string` + - `action: optional "generate" or "edit" or "auto"` - The name of the tool that was run. + Whether to generate a new image or edit an existing image. Default: `auto`. - - `server_label: string` + - `"generate"` - The label of the MCP server running the tool. + - `"edit"` - - `type: "mcp_call"` + - `"auto"` - The type of the item. Always `mcp_call`. + - `background: optional "transparent" or "opaque" or "auto"` - - `"mcp_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"` - - `approval_request_id: 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`. - 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. + - `"high"` - - `error: optional string` + - `"low"` - The error from the tool call, if any. + - `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). - The output from the tool call. + - `file_id: optional string` - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + File ID for the mask image. - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `image_url: optional string` - - `"in_progress"` + Base64-encoded mask image. - - `"completed"` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `"incomplete"` + The image generation model to use. Default: `gpt-image-1`. - - `"calling"` + - `string` - - `"failed"` + - `"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. + - `"gpt-image-1"` - - `id: string` + - `"gpt-image-1-mini"` - The unique ID of the list. + - `"gpt-image-1.5"` - - `server_label: string` + - `moderation: optional "auto" or "low"` - The label of the MCP server. + Moderation level for the generated image. Default: `auto`. - - `tools: array of object { input_schema, name, annotations, description }` + - `"auto"` - The tools available on the server. + - `"low"` - - `input_schema: unknown` + - `output_compression: optional number` - The JSON schema describing the tool's input. + Compression level for the output image. Default: 100. - - `name: string` + - `output_format: optional "png" or "webp" or "jpeg"` - The name of the tool. + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `annotations: optional unknown` + - `"png"` - Additional annotations about the tool. + - `"webp"` - - `description: optional string` + - `"jpeg"` - The description of the tool. + - `partial_images: optional number` - - `type: "mcp_list_tools"` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - The type of the item. Always `mcp_list_tools`. + - `quality: optional "low" or "medium" or "high" or "auto"` - - `"mcp_list_tools"` + 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"` - - `error: optional string` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - Error message if the server could not 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`. - - `McpApprovalRequest object { id, arguments, name, 3 more }` + - `string` - A request for human approval of a tool invocation. + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `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 unique ID of the approval request. + - `"1024x1024"` - - `arguments: string` + - `"1024x1536"` - A JSON string of arguments for the tool. + - `"1536x1024"` - - `name: string` + - `"auto"` - The name of the tool to run. + - `LocalShell object { type }` - - `server_label: string` + A tool that allows the model to execute shell commands in a local environment. - The label of the MCP server making the request. + - `type: "local_shell"` - - `type: "mcp_approval_request"` + The type of the local shell tool. Always `local_shell`. - The type of the item. Always `mcp_approval_request`. + - `"local_shell"` - - `"mcp_approval_request"` + - `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"` - - `McpApprovalResponse object { id, approval_request_id, approve, 3 more }` + - `allowed_callers: optional array of "direct" or "programmatic"` - A response to an MCP approval request. + The tool invocation context(s). - - `id: string` + - `"direct"` - The unique ID of the approval response + - `"programmatic"` - - `approval_request_id: string` + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - The ID of the approval request being answered. + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - - `approve: boolean` + - `BetaLocalEnvironment object { type, skills }` - Whether the request was approved. + - `BetaContainerReference object { container_id, type }` - - `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` - - `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"` - - `reason: optional string` + - `allowed_callers: optional array of "direct" or "programmatic"` - Optional reason for the decision. + The tool invocation context(s). - - `CustomToolCall object { call_id, input, name, 5 more }` + - `"direct"` - A call to a custom tool created by the model. + - `"programmatic"` - - `call_id: string` + - `defer_loading: optional boolean` - An identifier used to map this custom tool call to a tool call output. + Whether this tool should be deferred and discovered via tool search. - - `input: string` + - `description: optional string` - The input for the custom tool call generated by the model. + Optional description of the custom tool, used to provide more context. - - `name: string` + - `format: optional object { type } or object { definition, syntax, type }` - The name of the custom tool being called. + The input format for the custom tool. Default is unconstrained text. - - `type: "custom_tool_call"` + - `Text object { type }` - The type of the custom tool call. Always `custom_tool_call`. + Unconstrained free-form text. - - `"custom_tool_call"` + - `type: "text"` - - `id: optional string` + Unconstrained text format. Always `text`. - The unique ID of the custom tool call in the OpenAI platform. + - `"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. + - `Namespace object { description, name, tools, type }` - - `type: "program"` + Groups function/custom tools under a shared namespace. - - `"program"` + - `description: string` - - `namespace: optional string` + A description of the namespace shown to the model. - The namespace of the custom tool being called. + - `name: string` - - `CustomToolCallOutput object { id, call_id, output, 5 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 the custom tool call output item. + The function/custom tools available inside this namespace. - - `call_id: string` + - `Function object { name, type, allowed_callers, 5 more }` - 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` + - `type: "function"` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `"function"` - - `StringOutput = string` + - `allowed_callers: optional array of "direct" or "programmatic"` - A string of the output of the custom tool call. + The tool invocation context(s). - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `"direct"` - Text, image, or file output of the custom tool call. + - `"programmatic"` + + - `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` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `output_schema: optional map[unknown]` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `parameters: optional unknown` - A file input to the model. + - `strict: optional boolean` - - `status: "in_progress" or "completed" or "incomplete"` + 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 status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `Custom object { name, type, allowed_callers, 3 more }` - - `"in_progress"` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `"completed"` + - `name: string` - - `"incomplete"` + The name of the custom tool, used to identify it in tool calls. - - `type: "custom_tool_call_output"` + - `type: "custom"` - The type of the custom tool call output. Always `custom_tool_call_output`. + The type of the custom tool. Always `custom`. - - `"custom_tool_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"` - - `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 }` - - `created_by: optional string` + A grammar defined by the user. - The identifier of the actor that created the item. + - `definition: string` - - `parallel_tool_calls: boolean` + The grammar definition. - Whether to allow the model to run tool calls in parallel. + - `syntax: "lark" or "regex"` - - `temperature: number` + The syntax of the grammar definition. One of `lark` or `regex`. - 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. + - `"lark"` - - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` + - `"regex"` - 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: "grammar"` - - `BetaToolChoiceOptions = "none" or "auto" or "required"` + Grammar format. Always `grammar`. - Controls which (if any) tool is called by the model. + - `"grammar"` - `none` means the model will not call any tool and instead generates a message. + - `type: "namespace"` - `auto` means the model can pick between generating a message or calling one or - more tools. + The type of the tool. Always `namespace`. - `required` means the model must call one or more tools. + - `"namespace"` - - `"none"` + - `ToolSearch object { type, description, execution, parameters }` - - `"auto"` + Hosted or BYOT tool search configuration for deferred tools. - - `"required"` + - `type: "tool_search"` - - `BetaToolChoiceAllowed object { mode, tools, type }` + The type of the tool. Always `tool_search`. - Constrains the tools available to the model to a pre-defined set. + - `"tool_search"` - - `mode: "auto" or "required"` + - `description: optional string` - Constrains the tools available to the model to a pre-defined set. + Description shown to the model for a client-executed tool search tool. - `auto` allows the model to pick from among the allowed tools and generate a - message. + - `execution: optional "server" or "client"` - `required` requires the model to call one or more of the allowed tools. + Whether tool search is executed by the server or by the client. - - `"auto"` + - `"server"` - - `"required"` + - `"client"` - - `tools: array of map[unknown]` + - `parameters: optional unknown` - A list of tool definitions that the model should be allowed to call. + Parameter schema for a client-executed tool search tool. - For the Responses API, the list of tool definitions might look like: + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + 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: "allowed_tools"` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - Allowed tool configuration type. Always `allowed_tools`. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `"allowed_tools"` + - `"web_search_preview"` - - `BetaToolChoiceTypes object { type }` + - `"web_search_preview_2025_03_11"` - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + - `search_content_types: optional array of "text" or "image"` - - `type: "file_search" or "web_search_preview" or "computer" or 5 more` + - `"text"` - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + - `"image"` - Allowed values are: + - `search_context_size: optional "low" or "medium" or "high"` - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + 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"` + - `"low"` - - `"web_search_preview"` + - `"medium"` - - `"computer"` + - `"high"` - - `"computer_use_preview"` + - `user_location: optional object { type, city, country, 2 more }` - - `"computer_use"` + The user's location. - - `"web_search_preview_2025_03_11"` + - `type: "approximate"` - - `"image_generation"` + The type of location approximation. Always `approximate`. - - `"code_interpreter"` + - `"approximate"` - - `BetaToolChoiceFunction object { name, type }` + - `city: optional string` - Use this option to force the model to call a specific function. + Free text input for the city of the user, e.g. `San Francisco`. - - `name: string` + - `country: optional string` - The name of the function to call. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `type: "function"` + - `region: optional string` - For function calling, the type is always `function`. + Free text input for the region of the user, e.g. `California`. - - `"function"` + - `timezone: optional string` - - `BetaToolChoiceMcp object { server_label, type, name }` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - Use this option to force the model to call a specific tool on a remote MCP server. + - `ApplyPatch object { type, allowed_callers }` - - `server_label: string` + Allows the assistant to create, delete, or update files using unified diffs. - The label of the MCP server to use. + - `type: "apply_patch"` - - `type: "mcp"` + The type of the tool. Always `apply_patch`. - For MCP tools, the type is always `mcp`. + - `"apply_patch"` - - `"mcp"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `name: optional string` + The tool invocation context(s). - The name of the tool to call on the server. + - `"direct"` - - `BetaToolChoiceCustom object { name, type }` + - `"programmatic"` - Use this option to force the model to call a specific custom tool. + - `type: "tool_search_output"` - - `name: string` + The type of the item. Always `tool_search_output`. - The name of the custom tool to call. + - `"tool_search_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` - - `BetaSpecificProgrammaticToolCallingParam object { type }` + The canonical name of the agent that produced this item. - - `type: "programmatic_tool_calling"` + - `created_by: optional string` - The tool to call. Always `programmatic_tool_calling`. + The identifier of the actor that created the item. - - `"programmatic_tool_calling"` + - `AdditionalTools object { id, role, tools, 2 more }` - - `BetaToolChoiceApplyPatch object { type }` + - `id: string` - Forces the model to call the apply_patch tool when executing a tool call. + The unique ID of the additional tools item. - - `type: "apply_patch"` + - `role: "unknown" or "user" or "assistant" or 5 more` - The tool to call. Always `apply_patch`. + The role that provided the additional tools. - - `"apply_patch"` + - `"unknown"` - - `BetaToolChoiceShell object { type }` + - `"user"` - Forces the model to call the shell tool when a tool call is required. + - `"assistant"` - - `type: "shell"` + - `"system"` - The tool to call. Always `shell`. + - `"critic"` - - `"shell"` + - `"discriminator"` - - `tools: 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. + - `"tool"` - 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](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/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](https://platform.openai.com/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](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. + The additional tool definitions made available at this item. - `Function object { name, parameters, strict, 5 more }` @@ -120546,7 +118774,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-web-search). + [web search tool](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -120606,7 +118834,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -120658,7 +118886,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -120850,19 +119078,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `background: optional "transparent" or "opaque" or "auto"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. - - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. - - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - `"transparent"` @@ -120891,13 +119108,13 @@ curl -X POST https://api.openai.com/v1/responses/compact \ Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `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-2" or 3 more` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` The image generation model to use. Default: `gpt-image-1`. @@ -120905,14 +119122,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"gpt-image-1-mini"` - - `"gpt-image-2"` - - - `"gpt-image-2-2026-04-21"` - - `"gpt-image-1.5"` - - `"chatgpt-image-latest"` - - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -121009,7 +119220,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -121123,7 +119334,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -121291,2622 +119502,2926 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"programmatic"` - - `top_p: number` + - `type: "additional_tools"` - An alternative to sampling with temperature, called nucleus sampling, - where the model considers the results of the tokens with top_p probability - mass. So 0.1 means only the tokens comprising the top 10% probability mass - are considered. + The type of the item. Always `additional_tools`. - We generally recommend altering this or `temperature` but not both. + - `"additional_tools"` - - `background: optional boolean` + - `agent: optional object { agent_name }` - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + The agent that produced this item. - - `completed_at: optional number` + - `agent_name: string` - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + The canonical name of the agent that produced this item. - - `conversation: optional object { id }` + - `Compaction object { id, encrypted_content, type, 2 more }` - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). - `id: string` - The unique ID of the conversation that this response was associated with. + The unique ID of the compaction item. - - `max_output_tokens: optional number` + - `encrypted_content: string` - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + The encrypted content that was produced by compaction. - - `max_tool_calls: optional number` + - `type: "compaction"` - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + The type of the item. Always `compaction`. - - `moderation: optional object { input, output }` + - `"compaction"` - Moderation results for the response input and output, if moderated completions were requested. + - `agent: optional object { agent_name }` - - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + The agent that produced this item. - Moderation for the response input. + - `agent_name: string` - - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` + The canonical name of the agent that produced this item. - A moderation result produced for the response input or output. + - `created_by: optional string` - - `categories: map[boolean]` + The identifier of the actor that created the item. - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `ImageGenerationCall object { id, result, status, 2 more }` - - `category_applied_input_types: map[array of "text" or "image"]` + An image generation request made by the model. - Which modalities of input are reflected by the score for each category. + - `id: string` - - `"text"` + The unique ID of the image generation call. - - `"image"` + - `result: string` - - `category_scores: map[number]` + The generated image encoded in base64. - A dictionary of moderation categories to scores. + - `status: "in_progress" or "completed" or "generating" or "failed"` - - `flagged: boolean` + The status of the image generation call. - A boolean indicating whether the content was flagged by any category. + - `"in_progress"` - - `model: string` + - `"completed"` - The moderation model that produced this result. + - `"generating"` - - `type: "moderation_result"` + - `"failed"` - The object type, which was always `moderation_result` for successful moderation results. + - `type: "image_generation_call"` - - `"moderation_result"` + The type of the image generation call. Always `image_generation_call`. - - `Error object { code, message, type }` + - `"image_generation_call"` - An error produced while attempting moderation for the response input or 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. + + - `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 error code. + The code to run, or null if not available. - - `message: string` + - `container_id: string` - The error message. + The ID of the container used to run the code. - - `type: "error"` + - `outputs: array of object { logs, type } or object { type, url }` - The object type, which was always `error` for moderation failures. + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `"error"` + - `Logs object { logs, type }` - - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + The logs output from the code interpreter. - Moderation for the response output. + - `logs: string` - - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` + The logs output from the code interpreter. - A moderation result produced for the response input or output. + - `type: "logs"` - - `categories: map[boolean]` + The type of the output. Always `logs`. - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `"logs"` - - `category_applied_input_types: map[array of "text" or "image"]` + - `Image object { type, url }` - Which modalities of input are reflected by the score for each category. + The image output from the code interpreter. - - `"text"` + - `type: "image"` + + The type of the output. Always `image`. - `"image"` - - `category_scores: map[number]` + - `url: string` - A dictionary of moderation categories to scores. + The URL of the image output from the code interpreter. - - `flagged: boolean` + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - A boolean indicating whether the content was flagged by any category. + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `model: string` + - `"in_progress"` - The moderation model that produced this result. + - `"completed"` - - `type: "moderation_result"` + - `"incomplete"` - The object type, which was always `moderation_result` for successful moderation results. + - `"interpreting"` - - `"moderation_result"` + - `"failed"` - - `Error object { code, message, type }` + - `type: "code_interpreter_call"` - An error produced while attempting moderation for the response input or output. + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `code: string` + - `"code_interpreter_call"` - The error code. + - `agent: optional object { agent_name }` - - `message: string` + The agent that produced this item. - The error message. + - `agent_name: string` - - `type: "error"` + The canonical name of the agent that produced this item. - The object type, which was always `error` for moderation failures. + - `LocalShellCall object { id, action, call_id, 3 more }` - - `"error"` + A tool call to run a command on the local shell. - - `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](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + The unique ID of the local shell call. - - `prompt: optional BetaResponsePrompt` + - `action: object { command, env, type, 3 more }` - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + 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 identifier of the prompt template to use. + The unique ID of the local shell tool call generated by the model. - - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` + - `output: 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. + A JSON string of the output of the local shell tool call. - - `string` + - `type: "local_shell_call_output"` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + The type of the local shell tool call output. Always `local_shell_call_output`. - A text input to the model. + - `"local_shell_call_output"` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `agent: optional object { agent_name }` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + 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. - - `version: optional string` + - `status: optional "in_progress" or "completed" or "incomplete"` - Optional version of the prompt template. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `prompt_cache_key: optional string` + - `"in_progress"` - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + - `"completed"` - - `prompt_cache_options: optional object { mode, ttl }` + - `"incomplete"` - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + - `ShellCall object { id, action, call_id, 6 more }` - - `mode: "implicit" or "explicit"` + A tool call that executes one or more shell commands in a managed environment. - Whether implicit prompt-cache breakpoints were enabled. + - `id: string` - - `"implicit"` + The unique ID of the shell tool call. Populated when this item is returned via API. - - `"explicit"` + - `action: object { commands, max_output_length, timeout_ms }` - - `ttl: "30m"` + The shell commands and limits that describe how to run the tool call. - The minimum lifetime applied to each cache breakpoint. + - `commands: array of string` - - `"30m"` + - `max_output_length: number` - - `prompt_cache_retention: optional "in_memory" or "24h"` + Optional maximum number of characters to return from each command. - Deprecated. Use `prompt_cache_options.ttl` instead. + - `timeout_ms: 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](https://platform.openai.com/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. + Optional timeout in milliseconds for the commands. - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + - `call_id: string` - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + The unique ID of the shell tool call generated by the model. - - `"in_memory"` + - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` - - `"24h"` + Represents the use of a local environment to perform shell actions. - - `reasoning: optional object { context, effort, generate_summary, 2 more }` + - `BetaResponseLocalEnvironment object { type }` - **gpt-5 and o-series models only** + Represents the use of a local environment to perform shell actions. - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + - `type: "local"` - - `context: optional "auto" or "current_turn" or "all_turns"` + The environment type. Always `local`. - Controls which reasoning items are rendered back to the model on later turns. - When returned on a response, this is the effective reasoning context mode - used for the response. + - `"local"` - - `"auto"` + - `BetaResponseContainerReference object { container_id, type }` - - `"current_turn"` + Represents a container created with /v1/containers. - - `"all_turns"` + - `container_id: string` - - `effort: optional "none" or "minimal" or "low" or 4 more` + - `type: "container_reference"` - 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 environment type. Always `container_reference`. - - `"none"` + - `"container_reference"` - - `"minimal"` + - `status: "in_progress" or "completed" or "incomplete"` - - `"low"` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `"medium"` + - `"in_progress"` - - `"high"` + - `"completed"` - - `"xhigh"` + - `"incomplete"` - - `"max"` + - `type: "shell_call"` - - `generate_summary: optional "auto" or "concise" or "detailed"` + The type of the item. Always `shell_call`. - **Deprecated:** use `summary` instead. + - `"shell_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"` + - `caller: optional object { type } or object { caller_id, type }` - Controls the reasoning execution mode for the request. + The execution context that produced this tool call. - When returned on a response, this is the effective execution mode. + - `Direct object { type }` - - `string` + - `type: "direct"` - - `"standard" or "pro"` + - `"direct"` - Controls the reasoning execution mode for the request. + - `Program object { caller_id, type }` - When returned on a response, this is the effective execution mode. + - `caller_id: string` - - `"standard"` + The call ID of the program item that produced this tool call. - - `"pro"` + - `type: "program"` - - `summary: optional "auto" or "concise" or "detailed"` + - `"program"` - 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`. + - `created_by: optional string` - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + The ID of the entity that created this tool call. - - `"auto"` + - `ShellCallOutput object { id, call_id, max_output_length, 6 more }` - - `"concise"` + The output of a shell tool call that was emitted. - - `"detailed"` + - `id: string` - - `safety_identifier: optional string` + The unique ID of the shell call output. Populated when this item is returned via API. - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `call_id: string` - - `service_tier: optional "auto" or "default" or "flex" or 2 more` + The unique ID of the shell tool call generated by the model. - Specifies the processing type used for serving the request. + - `max_output_length: number` - - 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](https://platform.openai.com/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 maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - 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. + - `output: array of object { outcome, stderr, stdout, created_by }` - - `"auto"` + An array of shell call output contents - - `"default"` + - `outcome: object { type } or object { exit_code, type }` - - `"flex"` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - - `"scale"` + - `Timeout object { type }` - - `"priority"` + Indicates that the shell call exceeded its configured time limit. - - `status: optional BetaResponseStatus` + - `type: "timeout"` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + The outcome type. Always `timeout`. - - `"completed"` + - `"timeout"` - - `"failed"` + - `Exit object { exit_code, type }` - - `"in_progress"` + Indicates that the shell commands finished and returned an exit code. - - `"cancelled"` + - `exit_code: number` - - `"queued"` + Exit code from the shell process. + + - `type: "exit"` + + The outcome type. Always `exit`. + + - `"exit"` + + - `stderr: string` + + The standard error output that was captured. + + - `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"` - - `text: optional BetaResponseTextConfig` + - `type: "shell_call_output"` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + The type of the shell call output. Always `shell_call_output`. - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `"shell_call_output"` - - `format: optional BetaResponseFormatTextConfig` + - `agent: optional object { agent_name }` - An object specifying the format that the model must output. + The agent that produced this item. - Configuring `{ "type": "json_schema" }` enables Structured Outputs, - which ensures the model will match your supplied JSON schema. Learn more in the - [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `agent_name: string` - The default format is `{ "type": "text" }` with no additional options. + The canonical name of the agent that produced this item. - **Not recommended for gpt-4o and newer models:** + - `caller: optional object { type } or object { caller_id, type }` - 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 execution context that produced this tool call. - - `Text 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` - - `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](https://platform.openai.com/docs/guides/structured-outputs). + - `type: "program"` - - `name: string` + - `"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. + - `created_by: optional string` - - `schema: map[unknown]` + The identifier of the actor that created the item. - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `ApplyPatchCall object { id, call_id, operation, 5 more }` - - `type: "json_schema"` + A tool call that applies file diffs by creating, deleting, or updating files. - The type of response format being defined. Always `json_schema`. + - `id: string` - - `"json_schema"` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `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 apply patch tool call generated by the model. - - `strict: optional boolean` + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - 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](https://platform.openai.com/docs/guides/structured-outputs). + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `JSONObject object { type }` + - `CreateFile object { diff, path, 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. + Instruction describing how to create a file via the apply_patch tool. - - `type: "json_object"` + - `diff: string` - The type of response format being defined. Always `json_object`. + Diff to apply. - - `"json_object"` + - `path: string` - - `verbosity: optional "low" or "medium" or "high"` + Path of the file to create. - 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`. + - `type: "create_file"` - - `"low"` + Create a new file with the provided diff. - - `"medium"` + - `"create_file"` - - `"high"` + - `DeleteFile object { path, type }` - - `top_logprobs: optional number` + Instruction describing how to delete a file via the apply_patch tool. - 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. + - `path: string` - - `truncation: optional "auto" or "disabled"` + Path of the file to delete. - The truncation strategy to use for the model response. + - `type: "delete_file"` - - `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. + Delete the specified file. - - `"auto"` + - `"delete_file"` - - `"disabled"` + - `UpdateFile object { diff, path, type }` - - `usage: optional BetaResponseUsage` + Instruction describing how to update a file via the apply_patch tool. - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + - `diff: string` - - `input_tokens: number` + Diff to apply. - The number of input tokens. + - `path: string` - - `input_tokens_details: object { cache_write_tokens, cached_tokens }` + Path of the file to update. - A detailed breakdown of the input tokens. + - `type: "update_file"` - - `cache_write_tokens: number` + Update an existing file with the provided diff. - The number of input tokens that were written to the cache. + - `"update_file"` - - `cached_tokens: number` + - `status: "in_progress" or "completed"` - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `output_tokens: number` + - `"in_progress"` - The number of output tokens. + - `"completed"` - - `output_tokens_details: object { reasoning_tokens }` + - `type: "apply_patch_call"` - A detailed breakdown of the output tokens. + The type of the item. Always `apply_patch_call`. - - `reasoning_tokens: number` + - `"apply_patch_call"` - The number of reasoning tokens. + - `agent: optional object { agent_name }` - - `total_tokens: number` + The agent that produced this item. - The total number of tokens used. + - `agent_name: string` - - `user: optional string` + The canonical name of 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](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `caller: optional object { type } or object { caller_id, type }` - - `sequence_number: number` + The execution context that produced this tool call. - The sequence number of this event. + - `Direct object { type }` - - `type: "response.failed"` + - `type: "direct"` - The type of the event. Always `response.failed`. + - `"direct"` - - `"response.failed"` + - `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 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 File Search Call Completed Event + - `caller: optional object { type } or object { caller_id, type }` -- `BetaResponseFileSearchCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` + The execution context that produced this tool call. - Emitted when a file search call is completed (results found). + - `Direct object { type }` - - `item_id: string` + - `type: "direct"` - The ID of the output item that the file search call is initiated. + - `"direct"` - - `output_index: number` + - `Program object { caller_id, type }` - The index of the output item that the file search call is initiated. + - `caller_id: string` - - `sequence_number: number` + 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 sequence number of this event. + The description of the tool. - - `type: "response.file_search_call.completed"` + - `type: "mcp_list_tools"` - The type of the event. Always `response.file_search_call.completed`. + The type of the item. Always `mcp_list_tools`. - - `"response.file_search_call.completed"` + - `"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. -### Beta Response File Search Call In Progress Event + - `error: optional string` -- `BetaResponseFileSearchCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` + Error message if the server could not list tools. - Emitted when a file search call is initiated. + - `McpApprovalRequest object { id, arguments, name, 3 more }` - - `item_id: string` + A request for human approval of a tool invocation. - The ID of the output item that the file search call is initiated. + - `id: string` - - `output_index: number` + The unique ID of the approval request. - The index of the output item that the file search call is initiated. + - `arguments: string` - - `sequence_number: number` + A JSON string of arguments for the tool. - The sequence number of this event. + - `name: string` - - `type: "response.file_search_call.in_progress"` + The name of the tool to run. - The type of the event. Always `response.file_search_call.in_progress`. + - `server_label: string` - - `"response.file_search_call.in_progress"` + 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 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 File Search Call Searching Event - -- `BetaResponseFileSearchCallSearchingEvent object { item_id, output_index, sequence_number, 2 more }` + - `McpApprovalResponse object { id, approval_request_id, approve, 3 more }` - Emitted when a file search is currently searching. + A response to an MCP approval request. - - `item_id: string` + - `id: string` - The ID of the output item that the file search call is initiated. + The unique ID of the approval response - - `output_index: number` + - `approval_request_id: string` - The index of the output item that the file search call is searching. + The ID of the approval request being answered. - - `sequence_number: number` + - `approve: boolean` - The sequence number of this event. + Whether the request was approved. - - `type: "response.file_search_call.searching"` + - `type: "mcp_approval_response"` - The type of the event. Always `response.file_search_call.searching`. + The type of the item. Always `mcp_approval_response`. - - `"response.file_search_call.searching"` + - `"mcp_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. -### Beta Response Format Text Config - -- `BetaResponseFormatTextConfig = object { type } or BetaResponseFormatTextJSONSchemaConfig or object { type }` - - An object specifying the format that the model must output. + - `reason: optional 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](https://platform.openai.com/docs/guides/structured-outputs). + Optional reason for the decision. - The default format is `{ "type": "text" }` with no additional options. + - `CustomToolCall object { call_id, input, name, 5 more }` - **Not recommended for gpt-4o and newer models:** + A call to a custom tool created by the model. - 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. + - `call_id: string` - - `Text object { type }` + An identifier used to map this custom tool call to a tool call output. - Default response format. Used to generate text responses. + - `input: string` - - `type: "text"` + The input for the custom tool call generated by the model. - The type of response format being defined. Always `text`. + - `name: string` - - `"text"` + The name of the custom tool being called. - - `BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` + - `type: "custom_tool_call"` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + The type of the custom tool call. Always `custom_tool_call`. - - `name: string` + - `"custom_tool_call"` - 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. + - `id: optional string` - - `schema: map[unknown]` + The unique ID of the custom tool call in the OpenAI platform. - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `agent: optional object { agent_name }` - - `type: "json_schema"` + The agent that produced this item. - The type of response format being defined. Always `json_schema`. + - `agent_name: string` - - `"json_schema"` + The canonical name of the agent that produced this item. - - `description: optional string` + - `caller: optional object { type } or object { caller_id, type }` - A description of what the response format is for, used by the model to - determine how to respond in the format. + The execution context that produced this tool call. - - `strict: optional boolean` + - `Direct object { type }` - 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](https://platform.openai.com/docs/guides/structured-outputs). + - `type: "direct"` - - `JSONObject object { type }` + - `"direct"` - 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. + - `Program object { caller_id, type }` - - `type: "json_object"` + - `caller_id: string` - The type of response format being defined. Always `json_object`. + The call ID of the program item that produced this tool call. - - `"json_object"` + - `type: "program"` -### Beta Response Format Text JSON Schema Config + - `"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](https://platform.openai.com/docs/guides/structured-outputs). + The namespace of the custom tool being called. - - `name: string` + - `CustomToolCallOutput object { id, call_id, output, 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. + - `id: string` - - `schema: map[unknown]` + The unique ID of the custom tool call output item. - 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` - - `type: "json_schema"` + The call ID, used to map this custom tool call output to a custom tool call. - The type of response format being defined. Always `json_schema`. + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `"json_schema"` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `description: optional string` + - `StringOutput = string` - A description of what the response format is for, used by the model to - determine how to respond in the format. + A string of the output of the custom tool call. - - `strict: optional boolean` + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - 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](https://platform.openai.com/docs/guides/structured-outputs). + Text, image, or file output of the custom tool call. -### Beta Response Function Call Arguments Delta Event + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` -- `BetaResponseFunctionCallArgumentsDeltaEvent object { delta, item_id, output_index, 3 more }` + A text input to the model. - Emitted when there is a partial function-call arguments delta. + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `delta: string` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - The function-call arguments delta that is added. + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `item_id: string` + A file input to the model. - The ID of the output item that the function-call arguments delta is added to. + - `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 item that the function-call arguments delta is added to. + - `"in_progress"` - - `sequence_number: number` + - `"completed"` - The sequence number of this event. + - `"incomplete"` - - `type: "response.function_call_arguments.delta"` + - `type: "custom_tool_call_output"` - The type of the event. Always `response.function_call_arguments.delta`. + The type of the custom tool call output. Always `custom_tool_call_output`. - - `"response.function_call_arguments.delta"` + - `"custom_tool_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. -### Beta Response Function Call Arguments Done Event + - `caller: optional object { type } or object { caller_id, type }` -- `BetaResponseFunctionCallArgumentsDoneEvent object { arguments, item_id, name, 4 more }` + The execution context that produced this tool call. - Emitted when function-call arguments are finalized. + - `Direct object { type }` - - `arguments: string` + - `type: "direct"` - The function-call arguments. + The caller type. Always `direct`. - - `item_id: string` + - `"direct"` - The ID of the item. + - `Program object { caller_id, type }` - - `name: string` + - `caller_id: string` - The name of the function that was called. + The call ID of the program item that produced this tool call. - - `output_index: number` + - `type: "program"` - The index of the output item. + The caller type. Always `program`. - - `sequence_number: number` + - `"program"` - The sequence number of this event. + - `created_by: optional string` - - `type: "response.function_call_arguments.done"` + The identifier of the actor that created the item. - - `"response.function_call_arguments.done"` + - `parallel_tool_calls: boolean` - - `agent: optional object { agent_name }` + Whether to allow the model to run tool calls in parallel. - The agent that owns this multi-agent streaming event. + - `temperature: number` - - `agent_name: 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 canonical name of the agent that produced this item. + - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` -### Beta Response Function Call Output Item + 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. -- `BetaResponseFunctionCallOutputItem = BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` + - `BetaToolChoiceOptions = "none" or "auto" or "required"` - A piece of message content, such as text, an image, or a file. + Controls which (if any) tool is called by the model. - - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` + `none` means the model will not call any tool and instead generates a message. - A text input to the model. + `auto` means the model can pick between generating a message or calling one or + more tools. - - `text: string` + `required` means the model must call one or more tools. - The text input to the model. + - `"none"` - - `type: "input_text"` + - `"auto"` - The type of the input item. Always `input_text`. + - `"required"` - - `"input_text"` + - `BetaToolChoiceAllowed object { mode, tools, type }` - - `prompt_cache_breakpoint: optional object { mode }` + Constrains the tools available to the model to a pre-defined set. - Marks the exact end of a reusable 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: "auto" or "required"` - - `mode: "explicit"` + Constrains the tools available to the model to a pre-defined set. - The breakpoint mode. Always `explicit`. + `auto` allows the model to pick from among the allowed tools and generate a + message. - - `"explicit"` + `required` requires the model to call one or more of the allowed tools. - - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` + - `"auto"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `"required"` - - `type: "input_image"` + - `tools: array of map[unknown]` - The type of the input item. Always `input_image`. + A list of tool definitions that the model should be allowed to call. - - `"input_image"` + For the Responses API, the list of tool definitions might look like: - - `detail: optional "low" or "high" or "auto" or "original"` + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "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`. + - `type: "allowed_tools"` - - `"low"` + Allowed tool configuration type. Always `allowed_tools`. - - `"high"` + - `"allowed_tools"` - - `"auto"` + - `BetaToolChoiceTypes object { type }` - - `"original"` + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](/docs/guides/tools). - - `file_id: optional string` + - `type: "file_search" or "web_search_preview" or "computer" or 5 more` - The ID of the file to be sent to the model. + The type of hosted tool the model should to use. Learn more about + [built-in tools](/docs/guides/tools). - - `image_url: optional string` + Allowed values are: - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - - `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. + - `"web_search_preview"` - - `mode: "explicit"` + - `"computer"` - The breakpoint mode. Always `explicit`. + - `"computer_use_preview"` - - `"explicit"` + - `"computer_use"` - - `BetaResponseInputFileContent object { type, detail, file_data, 4 more }` + - `"web_search_preview_2025_03_11"` - A file input to the model. + - `"image_generation"` - - `type: "input_file"` + - `"code_interpreter"` - The type of the input item. Always `input_file`. + - `BetaToolChoiceFunction object { name, type }` - - `"input_file"` + Use this option to force the model to call a specific function. - - `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 function to call. - - `"auto"` + - `type: "function"` - - `"low"` + For function calling, the type is always `function`. - - `"high"` + - `"function"` - - `file_data: optional string` + - `BetaToolChoiceMcp object { server_label, type, name }` - The base64-encoded data of the file to be sent to the model. + Use this option to force the model to call a specific tool on a remote MCP server. - - `file_id: optional string` + - `server_label: string` - The ID of the file to be sent to the model. + The label of the MCP server to use. - - `file_url: optional string` + - `type: "mcp"` - The URL of the file to be sent to the model. + For MCP tools, the type is always `mcp`. - - `filename: optional string` + - `"mcp"` - The name of the file to be sent to the model. + - `name: optional string` - - `prompt_cache_breakpoint: optional object { mode }` + The name of the tool to call on the 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. + - `BetaToolChoiceCustom object { name, type }` - - `mode: "explicit"` + Use this option to force the model to call a specific custom tool. - The breakpoint mode. Always `explicit`. + - `name: string` - - `"explicit"` + The name of the custom tool to call. -### Beta Response Function Call Output Item List + - `type: "custom"` -- `BetaResponseFunctionCallOutputItemList = array of BetaResponseFunctionCallOutputItem` + For custom tool calling, the type is always `custom`. - An array of content outputs (text, image, file) for the function tool call. + - `"custom"` - - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` + - `BetaSpecificProgrammaticToolCallingParam object { type }` - A text input to the model. + - `type: "programmatic_tool_calling"` - - `text: string` + The tool to call. Always `programmatic_tool_calling`. - The text input to the model. + - `"programmatic_tool_calling"` - - `type: "input_text"` + - `BetaToolChoiceApplyPatch object { type }` - The type of the input item. Always `input_text`. + Forces the model to call the apply_patch tool when executing a tool call. - - `"input_text"` + - `type: "apply_patch"` - - `prompt_cache_breakpoint: optional object { mode }` + The tool to call. Always `apply_patch`. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `"apply_patch"` - - `mode: "explicit"` + - `BetaToolChoiceShell object { type }` - The breakpoint mode. Always `explicit`. + Forces the model to call the shell tool when a tool call is required. - - `"explicit"` + - `type: "shell"` - - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` + The tool to call. Always `shell`. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `"shell"` - - `type: "input_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` - The type of the input item. Always `input_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. - - `"input_image"` + We support the following categories of tools: - - `detail: optional "low" or "high" or "auto" or "original"` + - **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 detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `Function object { name, parameters, strict, 5 more }` - - `"low"` + 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). - - `"high"` + - `name: string` - - `"auto"` + The name of the function to call. - - `"original"` + - `parameters: map[unknown]` - - `file_id: optional string` + A JSON schema object describing the parameters of the function. - The ID of the file to be sent to the model. + - `strict: boolean` - - `image_url: optional string` + Whether strict parameter validation is enforced for this function tool. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `type: "function"` - - `prompt_cache_breakpoint: optional object { mode }` + The type of the function tool. Always `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. + - `"function"` - - `mode: "explicit"` + - `allowed_callers: optional array of "direct" or "programmatic"` - The breakpoint mode. Always `explicit`. + The tool invocation context(s). - - `"explicit"` + - `"direct"` - - `BetaResponseInputFileContent object { type, detail, file_data, 4 more }` + - `"programmatic"` - A file input to the model. + - `defer_loading: optional boolean` - - `type: "input_file"` + Whether this function is deferred and loaded via tool search. - The type of the input item. Always `input_file`. + - `description: optional string` - - `"input_file"` + A description of the function. Used by the model to determine whether or not to call the function. - - `detail: optional "auto" or "low" or "high"` + - `output_schema: optional map[unknown]` - 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 JSON schema object describing the JSON value encoded in string outputs for this function. - - `"auto"` + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - - `"low"` + 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"` + - `type: "file_search"` - - `file_data: optional string` + The type of the file search tool. Always `file_search`. - The base64-encoded data of the file to be sent to the model. + - `"file_search"` - - `file_id: optional string` + - `vector_store_ids: array of string` - The ID of the file to be sent to the model. + The IDs of the vector stores to search. - - `file_url: optional string` + - `filters: optional object { key, type, value } or object { filters, type }` - The URL of the file to be sent to the model. + A filter to apply. - - `filename: optional string` + - `ComparisonFilter object { key, type, value }` - The name of the file to be sent to the model. + 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 -### Beta Response Function Shell Call Output Content + - `"eq"` -- `BetaResponseFunctionShellCallOutputContent object { outcome, stderr, stdout }` + - `"ne"` - Captured stdout and stderr for a portion of a shell tool call output. + - `"gt"` - - `outcome: object { type } or object { exit_code, type }` + - `"gte"` - The exit or timeout outcome associated with this shell call. + - `"lt"` - - `Timeout object { type }` + - `"lte"` - Indicates that the shell call exceeded its configured time limit. + - `"in"` - - `type: "timeout"` + - `"nin"` - The outcome type. Always `timeout`. + - `value: string or number or boolean or array of string or number` - - `"timeout"` + The value to compare against the attribute key; supports string, number, or boolean types. - - `Exit object { exit_code, type }` + - `string` - Indicates that the shell commands finished and returned an exit code. + - `number` - - `exit_code: number` + - `boolean` - The exit code returned by the shell process. + - `array of string or number` - - `type: "exit"` + - `string` - The outcome type. Always `exit`. + - `number` - - `"exit"` + - `CompoundFilter object { filters, type }` - - `stderr: string` + Combine multiple filters using `and` or `or`. - Captured stderr output for the shell call. + - `filters: array of object { key, type, value } or unknown` - - `stdout: string` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - Captured stdout output for the shell call. + - `ComparisonFilter object { key, type, value }` -### Beta Response Image Gen Call Completed Event + A filter used to compare a specified attribute key to a given value using a defined comparison operation. -- `BetaResponseImageGenCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` + - `key: string` - Emitted when an image generation tool call has completed and the final image is available. + The key to compare against the value. - - `item_id: string` + - `type: "eq" or "ne" or "gt" or 5 more` - The unique identifier of the image generation item being processed. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `output_index: 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 index of the output item in the response's output array. + - `"eq"` - - `sequence_number: number` + - `"ne"` - The sequence number of this event. + - `"gt"` - - `type: "response.image_generation_call.completed"` + - `"gte"` - The type of the event. Always 'response.image_generation_call.completed'. + - `"lt"` - - `"response.image_generation_call.completed"` + - `"lte"` - - `agent: optional object { agent_name }` + - `"in"` - The agent that owns this multi-agent streaming event. + - `"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. -### Beta Response Image Gen Call Generating Event + - `string` -- `BetaResponseImageGenCallGeneratingEvent object { item_id, output_index, sequence_number, 2 more }` + - `number` - Emitted when an image generation tool call is actively generating an image (intermediate state). + - `boolean` - - `item_id: string` + - `array of string or number` - The unique identifier of the image generation item being processed. + - `string` - - `output_index: number` + - `number` - The index of the output item in the response's output array. + - `unknown` - - `sequence_number: number` + - `type: "and" or "or"` - The sequence number of the image generation item being processed. + Type of operation: `and` or `or`. - - `type: "response.image_generation_call.generating"` + - `"and"` - The type of the event. Always 'response.image_generation_call.generating'. + - `"or"` - - `"response.image_generation_call.generating"` + - `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 owns this multi-agent streaming event. + - `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 }` -### Beta Response Image Gen Call In Progress Event + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. -- `BetaResponseImageGenCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` + - `embedding_weight: number` - Emitted when an image generation tool call is in progress. + The weight of the embedding in the reciprocal ranking fusion. - - `item_id: string` + - `text_weight: number` - The unique identifier of the image generation item being processed. + The weight of the text in the reciprocal ranking fusion. - - `output_index: number` + - `ranker: optional "auto" or "default-2024-11-15"` - The index of the output item in the response's output array. + The ranker to use for the file search. - - `sequence_number: number` + - `"auto"` - The sequence number of the image generation item being processed. + - `"default-2024-11-15"` - - `type: "response.image_generation_call.in_progress"` + - `score_threshold: optional number` - The type of the event. Always 'response.image_generation_call.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. - - `"response.image_generation_call.in_progress"` + - `Computer object { 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 owns this multi-agent streaming event. + - `type: "computer"` - - `agent_name: string` + The type of the computer tool. Always `computer`. - The canonical name of the agent that produced this item. + - `"computer"` -### Beta Response Image Gen Call Partial Image Event + - `ComputerUsePreview object { display_height, display_width, environment, type }` -- `BetaResponseImageGenCallPartialImageEvent object { item_id, output_index, partial_image_b64, 4 more }` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - Emitted when a partial image is available during image generation streaming. + - `display_height: number` - - `item_id: string` + The height of the computer display. - The unique identifier of the image generation item being processed. + - `display_width: number` - - `output_index: number` + The width of the computer display. - The index of the output item in the response's output array. + - `environment: "windows" or "mac" or "linux" or 2 more` - - `partial_image_b64: string` + The type of computer environment to control. - Base64-encoded partial image data, suitable for rendering as an image. + - `"windows"` - - `partial_image_index: number` + - `"mac"` - 0-based index for the partial image (backend is 1-based, but this is 0-based for the user). + - `"linux"` - - `sequence_number: number` + - `"ubuntu"` - The sequence number of the image generation item being processed. + - `"browser"` - - `type: "response.image_generation_call.partial_image"` + - `type: "computer_use_preview"` - The type of the event. Always 'response.image_generation_call.partial_image'. + The type of the computer use tool. Always `computer_use_preview`. - - `"response.image_generation_call.partial_image"` + - `"computer_use_preview"` - - `agent: optional object { agent_name }` + - `WebSearch object { type, filters, search_context_size, user_location }` - The agent that owns this multi-agent streaming event. + 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`. -### Beta Response In Progress Event + - `"web_search"` -- `BetaResponseInProgressEvent object { response, sequence_number, type, agent }` + - `"web_search_2025_08_26"` - Emitted when the response is in progress. + - `filters: optional object { allowed_domains }` - - `response: BetaResponse` + Filters for the search. - The response that is in progress. + - `allowed_domains: optional array of string` - - `id: string` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - Unique identifier for this Response. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `created_at: number` + - `search_context_size: optional "low" or "medium" or "high"` - Unix timestamp (in seconds) of when this Response was 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. - - `error: BetaResponseError` + - `"low"` - An error object returned when the model fails to generate a Response. + - `"medium"` - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 16 more` + - `"high"` - The error code for the response. + - `user_location: optional object { city, country, region, 2 more }` - - `"server_error"` + The approximate location of the user. - - `"rate_limit_exceeded"` + - `city: optional string` - - `"invalid_prompt"` + Free text input for the city of the user, e.g. `San Francisco`. - - `"bio_policy"` + - `country: optional string` - - `"vector_store_timeout"` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `"invalid_image"` + - `region: optional string` - - `"invalid_image_format"` + Free text input for the region of the user, e.g. `California`. - - `"invalid_base64_image"` + - `timezone: optional string` - - `"invalid_image_url"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `"image_too_large"` + - `type: optional "approximate"` - - `"image_too_small"` + The type of location approximation. Always `approximate`. - - `"image_parse_error"` + - `"approximate"` - - `"image_content_policy_violation"` + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `"invalid_image_mode"` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - - `"image_file_too_large"` + - `server_label: string` - - `"unsupported_image_media_type"` + A label for this MCP server, used to identify it in tool calls. - - `"empty_image_file"` + - `type: "mcp"` - - `"failed_to_download_image"` + The type of the MCP tool. Always `mcp`. - - `"image_file_not_found"` + - `"mcp"` - - `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"` + - `allowed_tools: optional array of string or object { read_only, tool_names }` - The reason why the response is incomplete. + List of allowed tool names or a filter object. - - `"max_output_tokens"` + - `McpAllowedTools = array of string` - - `"content_filter"` + A string array of allowed tool names - - `instructions: string or array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + - `McpToolFilter object { read_only, tool_names }` - A system (or developer) message inserted into the model's context. + A filter object to specify which tools are allowed. - 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. + - `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 text input to the model, equivalent to a text input with the - `developer` role. + - `tool_names: optional array of string` - - `InputItemList = array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + List of allowed tool names. - A list of one or many input items to the model, containing - different content types. + - `authorization: optional string` - - `BetaEasyInputMessage object { content, role, phase, 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 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. + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `content: string or BetaResponseInputMessageContentList` + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + Currently supported `connector_id` values are: - - `TextInput = 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 text input to the model. + - `"connector_dropbox"` - - `BetaResponseInputMessageContentList = array of BetaResponseInputContent` + - `"connector_gmail"` - A list of one or many input items to the model, containing different content - types. + - `"connector_googlecalendar"` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `"connector_googledrive"` - A text input to the model. + - `"connector_microsoftteams"` - - `text: string` + - `"connector_outlookcalendar"` - The text input to the model. + - `"connector_outlookemail"` - - `type: "input_text"` + - `"connector_sharepoint"` - The type of the input item. Always `input_text`. + - `defer_loading: optional boolean` - - `"input_text"` + Whether this MCP tool is deferred and discovered via tool search. - - `prompt_cache_breakpoint: optional object { mode }` + - `headers: optional map[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 HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `mode: "explicit"` + - `require_approval: optional object { always, never } or "always" or "never"` - The breakpoint mode. Always `explicit`. + Specify which of the MCP server's tools require approval. - - `"explicit"` + - `McpToolApprovalFilter object { always, never }` - - `BetaResponseInputImage object { detail, type, file_id, 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. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `always: optional object { read_only, tool_names }` - - `detail: "low" or "high" or "auto" or "original"` + A filter object to specify which tools are allowed. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `read_only: optional boolean` - - `"low"` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `"high"` + - `tool_names: optional array of string` - - `"auto"` + List of allowed tool names. - - `"original"` + - `never: optional object { read_only, tool_names }` - - `type: "input_image"` + A filter object to specify which tools are allowed. - The type of the input item. Always `input_image`. + - `read_only: optional boolean` - - `"input_image"` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `file_id: optional string` + - `tool_names: optional array of string` - The ID of the file to be sent to the model. + List of allowed tool names. - - `image_url: optional string` + - `McpToolApprovalSetting = "always" or "never"` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + 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` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - A file input to the model. + - `tunnel_id: optional string` - - `type: "input_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 type of the input item. Always `input_file`. + - `CodeInterpreter object { container, type, allowed_callers }` - - `"input_file"` + A tool that runs Python code to help generate a response to a prompt. - - `detail: optional "auto" or "low" or "high"` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - 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 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"` - - `"low"` + - `file_ids: optional array of string` - - `"high"` + An optional list of uploaded files to make available to your code. - - `file_data: optional string` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - The content of the file to be sent to the model. + The memory limit for the code interpreter container. - - `file_id: optional string` + - `"1g"` - The ID of the file to be sent to the model. + - `"4g"` - - `file_url: optional string` + - `"16g"` - The URL of the file to be sent to the model. + - `"64g"` - - `filename: optional string` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - The name of the file to be sent to the model. + Network access policy for the container. - - `prompt_cache_breakpoint: optional object { mode }` + - `BetaContainerNetworkPolicyDisabled 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. + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `mode: "explicit"` + - `type: "code_interpreter"` - The breakpoint mode. Always `explicit`. + The type of the code interpreter tool. Always `code_interpreter`. - - `"explicit"` + - `"code_interpreter"` - - `role: "user" or "assistant" or "system" or "developer"` + - `allowed_callers: optional array of "direct" or "programmatic"` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + The tool invocation context(s). - - `"user"` + - `"direct"` - - `"assistant"` + - `"programmatic"` - - `"system"` + - `ProgrammaticToolCalling object { type }` - - `"developer"` + - `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. - - `type: optional "message"` + - `type: "image_generation"` - The type of the message input. Always `message`. + The type of the image generation tool. Always `image_generation`. - - `"message"` + - `"image_generation"` - - `Message object { content, role, agent, 2 more }` + - `action: optional "generate" or "edit" 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. + Whether to generate a new image or edit an existing image. Default: `auto`. - - `content: BetaResponseInputMessageContentList` + - `"generate"` - A list of one or many input items to the model, containing different content - types. + - `"edit"` - - `role: "user" or "system" or "developer"` + - `"auto"` - The role of the message input. One of `user`, `system`, or `developer`. + - `background: optional "transparent" or "opaque" or "auto"` - - `"user"` + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - - `"system"` + - `"transparent"` - - `"developer"` + - `"opaque"` - - `agent: optional object { agent_name }` + - `"auto"` - The agent that produced this item. + - `input_fidelity: optional "high" or "low"` - - `agent_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 canonical name of the agent that produced this item. + - `"high"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"low"` - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `input_image_mask: optional object { file_id, image_url }` - - `"in_progress"` + 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`. - - `"completed"` + - `string` - - `"incomplete"` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `type: optional "message"` + The image generation model to use. Default: `gpt-image-1`. - The type of the message input. Always set to `message`. + - `"gpt-image-1"` - - `"message"` + - `"gpt-image-1-mini"` - - `BetaResponseOutputMessage object { id, content, role, 4 more }` + - `"gpt-image-1.5"` - An output message from the model. + - `moderation: optional "auto" or "low"` - - `id: string` + Moderation level for the generated image. Default: `auto`. - The unique ID of the output message. + - `"auto"` - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + - `"low"` - The content of the output message. + - `output_compression: optional number` - - `BetaResponseOutputText object { annotations, text, type, logprobs }` + Compression level for the output image. Default: 100. - A text output from the model. + - `output_format: optional "png" or "webp" or "jpeg"` - - `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 output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - The annotations of the text output. + - `"png"` - - `FileCitation object { file_id, filename, index, type }` + - `"webp"` - A citation to a file. + - `"jpeg"` - - `file_id: string` + - `partial_images: optional number` - The ID of the file. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `filename: string` + - `quality: optional "low" or "medium" or "high" or "auto"` - The filename of the file cited. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `index: number` + - `"low"` - The index of the file in the list of files. + - `"medium"` - - `type: "file_citation"` + - `"high"` - The type of the file citation. Always `file_citation`. + - `"auto"` - - `"file_citation"` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `URLCitation object { end_index, start_index, title, 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`. - A citation for a web resource used to generate a model response. + - `string` - - `end_index: number` + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - The index of the last character of the URL citation in the 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`. - - `start_index: number` + - `"1024x1024"` - The index of the first character of the URL citation in the message. + - `"1024x1536"` - - `title: string` + - `"1536x1024"` - The title of the web resource. + - `"auto"` - - `type: "url_citation"` + - `LocalShell object { type }` - The type of the URL citation. Always `url_citation`. + A tool that allows the model to execute shell commands in a local environment. - - `"url_citation"` + - `type: "local_shell"` - - `url: string` + The type of the local shell tool. Always `local_shell`. - The URL of the web resource. + - `"local_shell"` - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + - `Shell object { type, allowed_callers, environment }` - A citation for a container file used to generate a model response. + A tool that allows the model to execute shell commands. - - `container_id: string` + - `type: "shell"` - The ID of the container file. + The type of the shell tool. Always `shell`. - - `end_index: number` + - `"shell"` - The index of the last character of the container file citation in the message. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `file_id: string` + The tool invocation context(s). - The ID of the file. + - `"direct"` - - `filename: string` + - `"programmatic"` - The filename of the container file cited. + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - `start_index: number` + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - The index of the first character of the container file citation in the message. + - `BetaLocalEnvironment object { type, skills }` - - `type: "container_file_citation"` + - `BetaContainerReference object { container_id, type }` - The type of the container file citation. 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) - - `FilePath object { file_id, index, type }` + - `name: string` - A path to a file. + The name of the custom tool, used to identify it in tool calls. - - `file_id: string` + - `type: "custom"` - The ID of the file. + 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_path"` + The tool invocation context(s). - The type of the file path. Always `file_path`. + - `"direct"` - - `"file_path"` + - `"programmatic"` - - `text: string` + - `defer_loading: optional boolean` - The text output from the model. + Whether this tool should be deferred and discovered via tool search. - - `type: "output_text"` + - `description: optional string` - The type of the output text. Always `output_text`. + Optional description of the custom tool, used to provide more context. - - `"output_text"` + - `format: optional object { type } or object { definition, syntax, type }` - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + The input format for the custom tool. Default is unconstrained text. - - `token: string` + - `Text object { type }` - - `bytes: array of number` + Unconstrained free-form text. - - `logprob: number` + - `type: "text"` - - `top_logprobs: array of object { token, bytes, logprob }` + Unconstrained text format. Always `text`. - - `token: string` + - `"text"` - - `bytes: array of number` + - `Grammar object { definition, syntax, type }` - - `logprob: number` + A grammar defined by the user. - - `BetaResponseOutputRefusal object { refusal, type }` + - `definition: string` - A refusal from the model. + The grammar definition. - - `refusal: string` + - `syntax: "lark" or "regex"` - The refusal explanation from the model. + The syntax of the grammar definition. One of `lark` or `regex`. - - `type: "refusal"` + - `"lark"` - The type of the refusal. Always `refusal`. + - `"regex"` - - `"refusal"` + - `type: "grammar"` - - `role: "assistant"` + Grammar format. Always `grammar`. - The role of the output message. Always `assistant`. + - `"grammar"` - - `"assistant"` + - `Namespace object { description, name, tools, type }` - - `status: "in_progress" or "completed" or "incomplete"` + Groups function/custom tools under a shared namespace. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `description: string` - - `"in_progress"` + A description of the namespace shown to the model. - - `"completed"` + - `name: string` - - `"incomplete"` + The namespace name used in tool calls (for example, `crm`). - - `type: "message"` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - The type of the output message. Always `message`. + The function/custom tools available inside this namespace. - - `"message"` + - `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"` - - `phase: optional "commentary" or "final_answer"` + The tool invocation context(s). - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + - `"direct"` - - `"commentary"` + - `"programmatic"` - - `"final_answer"` + - `defer_loading: optional boolean` - - `FileSearchCall object { id, queries, status, 3 more }` + Whether this function should be deferred and discovered via tool search. - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `description: optional string` - - `id: string` + - `output_schema: optional map[unknown]` - The unique ID of the file search tool call. + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `queries: array of string` + - `parameters: optional unknown` - The queries used to search for files. + - `strict: optional boolean` - - `status: "in_progress" or "searching" or "completed" or 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. - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `Custom object { name, type, allowed_callers, 3 more }` - - `"in_progress"` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `"searching"` + - `name: string` - - `"completed"` + The name of the custom tool, used to identify it in tool calls. - - `"incomplete"` + - `type: "custom"` - - `"failed"` + The type of the custom tool. Always `custom`. - - `type: "file_search_call"` + - `"custom"` - The type of the file search tool call. Always `file_search_call`. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"file_search_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 tool should be deferred and discovered via tool search. - - `results: optional array of object { attributes, file_id, filename, 2 more }` + - `description: optional string` - The results of the file search tool call. + Optional description of the custom tool, used to provide more context. - - `attributes: optional map[string or number or boolean]` + - `format: optional object { type } or object { definition, syntax, type }` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. Keys are strings - with a maximum length of 64 characters. Values are strings with a maximum - length of 512 characters, booleans, or numbers. + The input format for the custom tool. Default is unconstrained text. - - `string` + - `Text object { type }` - - `number` + Unconstrained free-form text. - - `boolean` + - `type: "text"` - - `file_id: optional string` + Unconstrained text format. Always `text`. - The unique ID of the file. + - `"text"` - - `filename: optional string` + - `Grammar object { definition, syntax, type }` - The name of the file. + A grammar defined by the user. - - `score: optional number` + - `definition: string` - The relevance score of the file - a value between 0 and 1. + The grammar definition. - - `text: optional string` + - `syntax: "lark" or "regex"` - The text that was retrieved from the file. + The syntax of the grammar definition. One of `lark` or `regex`. - - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` + - `"lark"` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + - `"regex"` - - `id: string` + - `type: "grammar"` - The unique ID of the computer call. + Grammar format. Always `grammar`. - - `call_id: string` + - `"grammar"` - An identifier used when responding to the tool call with output. + - `type: "namespace"` - - `pending_safety_checks: array of object { id, code, message }` + The type of the tool. Always `namespace`. - The pending safety checks for the computer call. + - `"namespace"` - - `id: string` + - `ToolSearch object { type, description, execution, parameters }` - The ID of the pending safety check. + Hosted or BYOT tool search configuration for deferred tools. - - `code: optional string` + - `type: "tool_search"` - The type of the pending safety check. + The type of the tool. Always `tool_search`. - - `message: optional string` + - `"tool_search"` - Details about the pending safety check. + - `description: optional string` - - `status: "in_progress" or "completed" or "incomplete"` + Description shown to the model 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. + - `execution: optional "server" or "client"` - - `"in_progress"` + Whether tool search is executed by the server or by the client. - - `"completed"` + - `"server"` - - `"incomplete"` + - `"client"` - - `type: "computer_call"` + - `parameters: optional unknown` - The type of the computer call. Always `computer_call`. + Parameter schema for a client-executed tool search tool. - - `"computer_call"` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - - `action: optional BetaComputerAction` + 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"` - - `Click object { button, type, x, 2 more }` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - A click action. + - `"web_search_preview"` - - `button: "left" or "right" or "wheel" or 2 more` + - `"web_search_preview_2025_03_11"` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `search_content_types: optional array of "text" or "image"` - - `"left"` + - `"text"` - - `"right"` + - `"image"` - - `"wheel"` + - `search_context_size: optional "low" or "medium" or "high"` - - `"back"` + 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. - - `"forward"` + - `"low"` - - `type: "click"` + - `"medium"` - Specifies the event type. For a click action, this property is always `click`. + - `"high"` - - `"click"` + - `user_location: optional object { type, city, country, 2 more }` - - `x: number` + The user's location. - The x-coordinate where the click occurred. + - `type: "approximate"` - - `y: number` + The type of location approximation. Always `approximate`. - The y-coordinate where the click occurred. + - `"approximate"` - - `keys: optional array of string` + - `city: optional string` - The keys being held while clicking. + Free text input for the city of the user, e.g. `San Francisco`. - - `DoubleClick object { keys, type, x, y }` + - `country: optional string` - A double click action. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `keys: array of string` + - `region: optional string` - The keys being held while double-clicking. + Free text input for the region of the user, e.g. `California`. - - `type: "double_click"` + - `timezone: optional string` - Specifies the event type. For a double click action, this property is always set to `double_click`. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `"double_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 double click occurred. + - `type: "apply_patch"` - - `y: number` + The type of the tool. Always `apply_patch`. - The y-coordinate where the double click occurred. + - `"apply_patch"` - - `Drag object { path, type, keys }` + - `allowed_callers: optional array of "direct" or "programmatic"` - A drag action. + The tool invocation context(s). - - `path: array of object { x, y }` + - `"direct"` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `"programmatic"` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `top_p: number` - - `x: 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 x-coordinate. + We generally recommend altering this or `temperature` but not both. - - `y: number` + - `background: optional boolean` - The y-coordinate. + Whether to run the model response in the background. + [Learn more](/docs/guides/background). - - `type: "drag"` + - `completed_at: optional number` - Specifies the event type. For a drag action, this property is always set to `drag`. + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - - `"drag"` + - `conversation: optional object { id }` - - `keys: optional array of string` + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - The keys being held while dragging the mouse. + - `id: string` - - `Keypress object { keys, type }` + The unique ID of the conversation that this response was associated with. - A collection of keypresses the model would like to perform. + - `max_output_tokens: optional number` - - `keys: array of 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 combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `max_tool_calls: optional number` - - `type: "keypress"` + 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. - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `moderation: optional object { input, output }` - - `"keypress"` + Moderation results for the response input and output, if moderated completions were requested. - - `Move object { type, x, y, keys }` + - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` - A mouse move action. + Moderation for the response input. - - `type: "move"` + - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` - Specifies the event type. For a move action, this property is always set to `move`. + A moderation result produced for the response input or output. - - `"move"` + - `categories: map[boolean]` - - `x: number` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - The x-coordinate to move to. + - `category_applied_input_types: map[array of "text" or "image"]` - - `y: number` + Which modalities of input are reflected by the score for each category. - The y-coordinate to move to. + - `"text"` - - `keys: optional array of string` + - `"image"` - The keys being held while moving the mouse. + - `category_scores: map[number]` - - `Screenshot object { type }` + A dictionary of moderation categories to scores. - A screenshot action. + - `flagged: boolean` - - `type: "screenshot"` + A boolean indicating whether the content was flagged by any category. - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `model: string` - - `"screenshot"` + The moderation model that produced this result. - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `type: "moderation_result"` - A scroll action. + The object type, which was always `moderation_result` for successful moderation results. - - `scroll_x: number` + - `"moderation_result"` - The horizontal scroll distance. + - `Error object { code, message, type }` - - `scroll_y: number` + An error produced while attempting moderation for the response input or output. - The vertical scroll distance. + - `code: string` - - `type: "scroll"` + The error code. - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `message: string` - - `"scroll"` + The error message. - - `x: number` + - `type: "error"` - The x-coordinate where the scroll occurred. + The object type, which was always `error` for moderation failures. - - `y: number` + - `"error"` - The y-coordinate where the scroll occurred. + - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` - - `keys: optional array of string` + Moderation for the response output. - The keys being held while scrolling. + - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` - - `Type object { text, type }` + A moderation result produced for the response input or output. - An action to type in text. + - `categories: map[boolean]` - - `text: string` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - The text to type. + - `category_applied_input_types: map[array of "text" or "image"]` - - `type: "type"` + Which modalities of input are reflected by the score for each category. - Specifies the event type. For a type action, this property is always set to `type`. + - `"text"` - - `"type"` + - `"image"` - - `Wait object { type }` + - `category_scores: map[number]` - A wait action. + A dictionary of moderation categories to scores. - - `type: "wait"` + - `flagged: boolean` - Specifies the event type. For a wait action, this property is always set to `wait`. + A boolean indicating whether the content was flagged by any category. - - `"wait"` + - `model: string` - - `actions: optional BetaComputerActionList` + The moderation model that produced this result. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `type: "moderation_result"` - - `Click object { button, type, x, 2 more }` + The object type, which was always `moderation_result` for successful moderation results. - A click action. + - `"moderation_result"` - - `DoubleClick object { keys, type, x, y }` + - `Error object { code, message, type }` - A double click action. + An error produced while attempting moderation for the response input or output. - - `Drag object { path, type, keys }` + - `code: string` - A drag action. + The error code. - - `Keypress object { keys, type }` + - `message: string` - A collection of keypresses the model would like to perform. + The error message. - - `Move object { type, x, y, keys }` + - `type: "error"` - A mouse move action. + The object type, which was always `error` for moderation failures. - - `Screenshot object { type }` + - `"error"` - A screenshot action. + - `output_text: optional string` - - `Scroll object { scroll_x, scroll_y, type, 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. - A scroll action. + - `previous_response_id: optional string` - - `Type object { text, 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`. - An action to type in text. + - `prompt: optional BetaResponsePrompt` - - `Wait object { type }` + Reference to a prompt template and its variables. + [Learn more](/docs/guides/text?api-mode=responses#reusable-prompts). - A wait action. + - `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` - - `ComputerCallOutput object { call_id, output, type, 4 more }` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - The output of a computer tool call. + A text input to 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` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - A computer screenshot image used with the computer use tool. + A file input to the model. - - `type: "computer_screenshot"` + - `version: optional string` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + Optional version of the prompt template. - - `"computer_screenshot"` + - `prompt_cache_key: optional string` - - `file_id: 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). - The identifier of an uploaded file that contains the screenshot. + - `prompt_cache_options: optional object { mode, ttl }` - - `image_url: optional string` + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - The URL of the screenshot image. + - `mode: "implicit" or "explicit"` - - `type: "computer_call_output"` + Whether implicit prompt-cache breakpoints were enabled. - The type of the computer tool call output. Always `computer_call_output`. + - `"implicit"` - - `"computer_call_output"` + - `"explicit"` - - `id: optional string` + - `ttl: "30m"` - The ID of the computer tool call output. + The minimum lifetime applied to each cache breakpoint. - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `"30m"` - The safety checks reported by the API that have been acknowledged by the developer. + - `prompt_cache_retention: optional "in_memory" or "24h"` - - `id: string` + Deprecated. Use `prompt_cache_options.ttl` instead. - The ID of the pending safety check. + 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. - - `code: optional string` + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - The type of the pending safety check. + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - - `message: optional string` + - `"in_memory"` - Details about the pending safety check. + - `"24h"` - - `agent: optional object { agent_name }` + - `reasoning: optional object { context, effort, generate_summary, 2 more }` - The agent that produced this item. + **gpt-5 and o-series models only** - - `agent_name: string` + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - The canonical name of the agent that produced this item. + - `context: optional "auto" or "current_turn" or "all_turns"` - - `status: optional "in_progress" or "completed" or "incomplete"` + Controls which reasoning items are rendered back to the model on later turns. + When returned on a response, this is the effective reasoning context mode + used for the response. - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + - `"auto"` - - `"in_progress"` + - `"current_turn"` - - `"completed"` + - `"all_turns"` - - `"incomplete"` + - `effort: optional "none" or "minimal" or "low" or 4 more` - - `WebSearchCall object { id, action, status, 2 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. - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `"none"` - - `id: string` + - `"minimal"` - The unique ID of the web search tool call. + - `"low"` - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + - `"medium"` - 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). + - `"high"` - - `Search object { type, queries, query, sources }` + - `"xhigh"` - Action type "search" - Performs a web search query. + - `"max"` - - `type: "search"` + - `generate_summary: optional "auto" or "concise" or "detailed"` - The action type. + **Deprecated:** use `summary` instead. - - `"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`. - - `queries: optional array of string` + - `"auto"` - The search queries. + - `"concise"` - - `query: optional string` + - `"detailed"` - The search query. + - `mode: optional string or "standard" or "pro"` - - `sources: optional array of object { type, url }` + Controls the reasoning execution mode for the request. - The sources used in the search. + When returned on a response, this is the effective execution mode. - - `type: "url"` + - `string` - The type of source. Always `url`. + - `"standard" or "pro"` - - `"url"` + Controls the reasoning execution mode for the request. - - `url: string` + When returned on a response, this is the effective execution mode. - The URL of the source. + - `"standard"` - - `OpenPage object { type, url }` + - `"pro"` - Action type "open_page" - Opens a specific URL from search results. + - `summary: optional "auto" or "concise" or "detailed"` - - `type: "open_page"` + 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 type. + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - - `"open_page"` + - `"auto"` - - `url: optional string` + - `"concise"` - The URL opened by the model. + - `"detailed"` - - `FindInPage object { pattern, type, url }` + - `safety_identifier: optional string` - Action type "find_in_page": Searches for a pattern within a loaded page. + 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). - - `pattern: string` + - `service_tier: optional "auto" or "default" or "flex" or 2 more` - The pattern or text to search for within the page. + Specifies the processing type used for serving the request. - - `type: "find_in_page"` + - 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 action type. + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. - - `"find_in_page"` + - `"auto"` - - `url: string` + - `"default"` - The URL of the page searched for the pattern. + - `"flex"` - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `"scale"` - The status of the web search tool call. + - `"priority"` - - `"in_progress"` + - `status: optional BetaResponseStatus` - - `"searching"` + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - `"completed"` - `"failed"` - - `type: "web_search_call"` + - `"in_progress"` - The type of the web search tool call. Always `web_search_call`. + - `"cancelled"` - - `"web_search_call"` + - `"queued"` - - `agent: optional object { agent_name }` + - `"incomplete"` - The agent that produced this item. + - `text: optional BetaResponseTextConfig` - - `agent_name: string` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - The canonical name of the agent that produced this item. + - [Text inputs and outputs](/docs/guides/text) + - [Structured Outputs](/docs/guides/structured-outputs) - - `FunctionCall object { arguments, call_id, name, 6 more }` + - `format: optional BetaResponseFormatTextConfig` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + An object specifying the format that the model must output. - - `arguments: 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). - A JSON string of the arguments to pass to the function. + The default format is `{ "type": "text" }` with no additional options. - - `call_id: string` + **Not recommended for gpt-4o and newer models:** - The unique ID of the function tool call generated by the model. + 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 function to run. + Default response format. Used to generate text responses. - - `type: "function_call"` + - `type: "text"` - The type of the function tool call. Always `function_call`. + The type of response format being defined. Always `text`. - - `"function_call"` + - `"text"` - - `id: optional string` + - `BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` - The unique ID of the function tool call. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - - `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` + - `schema: map[unknown]` - The canonical name of the agent that produced this item. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `caller: optional object { type } or object { caller_id, type }` + - `type: "json_schema"` - The execution context that produced this tool call. + The type of response format being defined. Always `json_schema`. - - `Direct object { type }` + - `"json_schema"` - - `type: "direct"` + - `description: optional string` - - `"direct"` + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `Program object { caller_id, type }` + - `strict: optional boolean` - - `caller_id: string` + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](/docs/guides/structured-outputs). - The call ID of the program item that produced this tool call. + - `JSONObject object { type }` - - `type: "program"` + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - - `"program"` + - `type: "json_object"` - - `namespace: optional string` + The type of response format being defined. Always `json_object`. - The namespace of the function to run. + - `"json_object"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `verbosity: optional "low" or "medium" or "high"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + 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`. - - `"in_progress"` + - `"low"` - - `"completed"` + - `"medium"` - - `"incomplete"` + - `"high"` - - `FunctionCallOutput object { call_id, output, type, 4 more }` + - `top_logprobs: optional number` - The output of a function tool call. + 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. - - `call_id: string` + - `truncation: optional "auto" or "disabled"` - The unique ID of the function tool call generated by the model. + The truncation strategy to use for the model response. - - `output: string or BetaResponseFunctionCallOutputItemList` + - `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. - Text, image, or file output of the function tool call. + - `"auto"` - - `string` + - `"disabled"` - A JSON string of the output of the function tool call. + - `usage: optional BetaResponseUsage` - - `BetaResponseFunctionCallOutputItemList = array of BetaResponseFunctionCallOutputItem` + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - An array of content outputs (text, image, file) for the function tool call. + - `input_tokens: number` - - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` + The number of input tokens. - A text input to the model. + - `input_tokens_details: object { cache_write_tokens, cached_tokens }` - - `text: string` + A detailed breakdown of the input tokens. - The text input to the model. + - `cache_write_tokens: number` - - `type: "input_text"` + The number of input tokens that were written to the cache. - The type of the input item. Always `input_text`. + - `cached_tokens: number` - - `"input_text"` + The number of tokens that were retrieved from the cache. + [More on prompt caching](/docs/guides/prompt-caching). - - `prompt_cache_breakpoint: optional object { mode }` + - `output_tokens: 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 number of output tokens. - - `mode: "explicit"` + - `output_tokens_details: object { reasoning_tokens }` - The breakpoint mode. Always `explicit`. + A detailed breakdown of the output tokens. - - `"explicit"` + - `reasoning_tokens: number` - - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` + The number of reasoning tokens. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `total_tokens: number` - - `type: "input_image"` + The total number of tokens used. - The type of the input item. Always `input_image`. + - `user: optional string` - - `"input_image"` + 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). - - `detail: optional "low" or "high" or "auto" or "original"` + - `sequence_number: number` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The sequence number of this event. - - `"low"` + - `type: "response.incomplete"` - - `"high"` + The type of the event. Always `response.incomplete`. - - `"auto"` + - `"response.incomplete"` - - `"original"` + - `agent: optional object { agent_name }` - - `file_id: optional string` + The agent that owns this multi-agent streaming event. - 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. +### Beta Response Inject Created Event - - `prompt_cache_breakpoint: optional object { mode }` +- `BetaResponseInjectCreatedEvent object { response_id, sequence_number, type, stream_id }` - Marks the exact end of a reusable 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 all injected input items were validated and committed to the + active response. - - `mode: "explicit"` + - `response_id: string` - The breakpoint mode. Always `explicit`. + The ID of the response that accepted the input. - - `"explicit"` + - `sequence_number: number` - - `BetaResponseInputFileContent object { type, detail, file_data, 4 more }` + The sequence number for this event. - A file input to the model. + - `type: "response.inject.created"` - - `type: "input_file"` + The event discriminator. Always `response.inject.created`. - The type of the input item. Always `input_file`. + - `"response.inject.created"` - - `"input_file"` + - `stream_id: optional string` - - `detail: optional "auto" or "low" or "high"` + The multiplexed WebSocket stream that emitted the event. This field is + present only when WebSocket multiplexing is enabled separately. - 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`. +### Beta Response Inject Event - - `"auto"` +- `BetaResponseInjectEvent object { input, response_id, type }` - - `"low"` + 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. - - `"high"` + - `input: array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` - - `file_data: optional string` + Input items to inject into the active response. - The base64-encoded data of the file to be sent to the model. + - `BetaEasyInputMessage object { content, role, phase, type }` - - `file_id: optional 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 file to be sent to the model. + - `content: string or BetaResponseInputMessageContentList` - - `file_url: optional string` + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - The URL of the file to be sent to the model. + - `TextInput = string` - - `filename: optional string` + A text input to the model. - The name of the file to be sent to the model. + - `BetaResponseInputMessageContentList = array of BetaResponseInputContent` - - `prompt_cache_breakpoint: optional object { mode }` + A list of one or many input items to the model, containing different content + types. - Marks the exact end of a reusable 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`. + - `text: string` - - `"explicit"` + The text input to the model. - - `type: "function_call_output"` + - `type: "input_text"` - The type of the function tool call output. Always `function_call_output`. + The type of the input item. Always `input_text`. - - `"function_call_output"` + - `"input_text"` - - `id: optional string` + - `prompt_cache_breakpoint: optional object { mode }` - The unique ID of the function tool call output. Populated when this item is returned via API. + Marks the exact end of a reusable 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 }` - - `caller: optional object { type } or object { caller_id, type }` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - The execution context that produced this tool call. + - `detail: "low" or "high" or "auto" or "original"` - - `Direct object { type }` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `type: "direct"` + - `"low"` - The caller type. Always `direct`. + - `"high"` - - `"direct"` + - `"auto"` - - `Program object { caller_id, type }` + - `"original"` - - `caller_id: string` + - `type: "input_image"` - The call ID of the program item that produced this tool call. + The type of the input item. Always `input_image`. - - `type: "program"` + - `"input_image"` + + - `file_id: optional string` - The caller type. Always `program`. + The ID of the file to be sent to the model. - - `"program"` + - `image_url: optional string` - - `status: optional "in_progress" or "completed" or "incomplete"` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + - `prompt_cache_breakpoint: optional object { mode }` - - `"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. - - `"completed"` + - `mode: "explicit"` - - `"incomplete"` + The breakpoint mode. Always `explicit`. - - `AgentMessage object { author, content, recipient, 3 more }` + - `"explicit"` - A message routed between agents. + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `author: string` + A file input to the model. - The sending agent identity. + - `type: "input_file"` - - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` + The type of the input item. Always `input_file`. - Plaintext, image, or encrypted content sent between agents. + - `"input_file"` - - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` + - `detail: optional "auto" or "low" or "high"` - A text input to the model. + 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`. - - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` + - `"auto"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `"low"` - - `EncryptedContent object { encrypted_content, type }` + - `"high"` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `file_data: optional string` - - `encrypted_content: string` + The content of the file to be sent to the model. - Opaque encrypted content. + - `file_id: optional string` - - `type: "encrypted_content"` + The ID of the file to be sent to the model. - The type of the input item. Always `encrypted_content`. + - `file_url: optional string` - - `"encrypted_content"` + The URL of the file to be sent to the model. - - `recipient: string` + - `filename: optional string` - The destination agent identity. + The name of the file to be sent to the model. - - `type: "agent_message"` + - `prompt_cache_breakpoint: optional object { mode }` - The item type. Always `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. - - `"agent_message"` + - `mode: "explicit"` - - `id: optional string` + The breakpoint mode. Always `explicit`. - The unique ID of this agent message item. + - `"explicit"` - - `agent: optional object { agent_name }` + - `role: "user" or "assistant" or "system" or "developer"` - The agent that produced this item. + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - - `agent_name: string` + - `"user"` - The canonical name of the agent that produced this item. + - `"assistant"` - - `MultiAgentCall object { action, arguments, call_id, 3 more }` + - `"system"` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `"developer"` - The multi-agent action that was executed. + - `phase: optional "commentary" or "final_answer"` - - `"spawn_agent"` + 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. - - `"interrupt_agent"` + - `"commentary"` - - `"list_agents"` + - `"final_answer"` - - `"send_message"` + - `type: optional "message"` - - `"followup_task"` + The type of the message input. Always `message`. - - `"wait_agent"` + - `"message"` - - `arguments: string` + - `Message object { content, role, agent, 2 more }` - The action arguments as a JSON 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. - - `call_id: string` + - `content: BetaResponseInputMessageContentList` - The unique ID linking this call to its output. + A list of one or many input items to the model, containing different content + types. - - `type: "multi_agent_call"` + - `role: "user" or "system" or "developer"` - The item type. Always `multi_agent_call`. + The role of the message input. One of `user`, `system`, or `developer`. - - `"multi_agent_call"` + - `"user"` - - `id: optional string` + - `"system"` - The unique ID of this multi-agent call. + - `"developer"` - `agent: optional object { agent_name }` @@ -123916,47 +122431,46 @@ 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` + - `status: optional "in_progress" or "completed" or "incomplete"` - The multi-agent action that produced this result. + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"spawn_agent"` + - `"in_progress"` - - `"interrupt_agent"` + - `"completed"` - - `"list_agents"` + - `"incomplete"` - - `"send_message"` + - `type: optional "message"` - - `"followup_task"` + The type of the message input. Always set to `message`. - - `"wait_agent"` + - `"message"` - - `call_id: string` + - `BetaResponseOutputMessage object { id, content, role, 4 more }` - The unique ID of the multi-agent call. + An output message from the model. - - `output: array of object { text, type, annotations }` + - `id: string` - Text output returned by the multi-agent action. + The unique ID of the output message. - - `text: string` + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - The text content. + The content of the output message. - - `type: "output_text"` + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - The content type. Always `output_text`. + A text output from the model. - - `"output_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 }` - - `annotations: optional array of object { file_id, filename, index, type } or array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` + The annotations of the text output. - Citations associated with the text content. + - `FileCitation object { file_id, filename, index, type }` - - `array of object { file_id, filename, index, type }` + A citation to a file. - `file_id: string` @@ -123972,47 +122486,51 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "file_citation"` - The citation type. Always `file_citation`. + The type of the file citation. Always `file_citation`. - `"file_citation"` - - `array of object { end_index, start_index, title, 2 more }` + - `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 citation in the message. + The index of the last character of the URL citation in the message. - `start_index: number` - The index of the first character of the citation in the message. + The index of the first character of the URL citation in the message. - `title: string` - The title of the cited resource. + The title of the web resource. - `type: "url_citation"` - The citation type. Always `url_citation`. + The type of the URL citation. Always `url_citation`. - `"url_citation"` - `url: string` - The URL of the cited resource. + The URL of the web resource. - - `array of object { container_id, end_index, file_id, 3 more }` + - `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. + The ID of the container file. - `end_index: number` - The index of the last character of the citation in the message. + The index of the last character of the container file citation in the message. - `file_id: string` - The ID of the container file. + The ID of the file. - `filename: string` @@ -124020,184 +122538,166 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `start_index: number` - The index of the first character of the citation in the message. + The index of the first character of the container file citation in the message. - `type: "container_file_citation"` - The citation type. Always `container_file_citation`. + The type of the container file citation. 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` + - `FilePath object { file_id, index, type }` - The arguments supplied to the tool search call. + A path to a file. - - `type: "tool_search_call"` + - `file_id: string` - The item type. Always `tool_search_call`. + The ID of the file. - - `"tool_search_call"` + - `index: number` - - `id: optional string` + The index of the file in the list of files. - The unique ID of this tool search call. + - `type: "file_path"` - - `agent: optional object { agent_name }` + The type of the file path. Always `file_path`. - The agent that produced this item. + - `"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` - - `call_id: optional string` + - `bytes: array of number` - The unique ID of the tool search call generated by the model. + - `logprob: number` - - `execution: optional "server" or "client"` + - `top_logprobs: array of object { token, bytes, logprob }` - Whether tool search was executed by the server or by the client. + - `token: string` - - `"server"` + - `bytes: array of number` - - `"client"` + - `logprob: number` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `text: string` - The status of the tool search call. + The text output from the model. - - `"in_progress"` + - `type: "output_text"` - - `"completed"` + The type of the output text. Always `output_text`. - - `"incomplete"` + - `"output_text"` - - `ToolSearchOutput object { tools, type, id, 4 more }` + - `BetaResponseOutputRefusal object { refusal, type }` - - `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 refusal from the model. - The loaded tool definitions returned by the tool search output. + - `refusal: string` - - `Function object { name, parameters, strict, 5 more }` + The refusal explanation 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). + - `type: "refusal"` - - `name: string` + The type of the refusal. Always `refusal`. - The name of the function to call. + - `"refusal"` - - `parameters: map[unknown]` + - `role: "assistant"` - A JSON schema object describing the parameters of the function. + The role of the output message. Always `assistant`. - - `strict: boolean` + - `"assistant"` - Whether strict parameter validation is enforced for this function tool. + - `status: "in_progress" or "completed" or "incomplete"` - - `type: "function"` + 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 function tool. Always `function`. + - `"in_progress"` - - `"function"` + - `"completed"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"incomplete"` - The tool invocation context(s). + - `type: "message"` - - `"direct"` + The type of the output message. Always `message`. - - `"programmatic"` + - `"message"` - - `defer_loading: optional boolean` + - `agent: optional object { agent_name }` - Whether this function is deferred and loaded via tool search. + The agent that produced this item. - - `description: optional string` + - `agent_name: string` - A description of the function. Used by the model to determine whether or not to call the function. + The canonical name of the agent that produced this item. - - `output_schema: optional map[unknown]` + - `phase: optional "commentary" or "final_answer"` - A JSON schema object describing the JSON value encoded in string outputs for this function. + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + - `"commentary"` - 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). + - `"final_answer"` - - `type: "file_search"` + - `FileSearchCall object { id, queries, status, 3 more }` - The type of the file search tool. Always `file_search`. + The results of a file search tool call. See the + [file search guide](/docs/guides/tools-file-search) for more information. - - `"file_search"` + - `id: string` - - `vector_store_ids: array of string` + The unique ID of the file search tool call. - The IDs of the vector stores to search. + - `queries: array of string` - - `filters: optional object { key, type, value } or object { filters, type }` + The queries used to search for files. - A filter to apply. + - `status: "in_progress" or "searching" or "completed" or 2 more` - - `ComparisonFilter object { key, type, value }` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `"in_progress"` - - `key: string` + - `"searching"` - The key to compare against the value. + - `"completed"` - - `type: "eq" or "ne" or "gt" or 5 more` + - `"incomplete"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `"failed"` - - `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: "file_search_call"` - - `"eq"` + The type of the file search tool call. Always `file_search_call`. - - `"ne"` + - `"file_search_call"` - - `"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"` + - `results: optional array of object { attributes, file_id, filename, 2 more }` - - `"nin"` + The results of the file search tool call. - - `value: string or number or boolean or array of string or number` + - `attributes: optional map[string or number or boolean]` - The value to compare against the attribute key; supports string, number, or boolean types. + 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` @@ -124205,1064 +122705,984 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/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](https://platform.openai.com/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](https://platform.openai.com/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. - - `type: "disabled"` + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - Disable outbound network access. Always `disabled`. + 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). - - `"disabled"` + - `Search object { type, queries, query, sources }` - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + Action type "search" - Performs a web search query. - - `allowed_domains: array of string` + - `type: "search"` - A list of allowed domains when type is `allowlist`. + The action type. - - `type: "allowlist"` + - `"search"` - Allow outbound network access only to specified domains. Always `allowlist`. + - `queries: optional array of string` - - `"allowlist"` + The search queries. - - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` + - `query: optional string` - Optional domain-scoped secrets for allowlisted domains. + The search query. - - `domain: string` + - `sources: optional array of object { type, url }` - The domain associated with the secret. + The sources used in the search. - - `name: string` + - `type: "url"` - The name of the secret to inject for the domain. + The type of source. Always `url`. - - `value: string` + - `"url"` - The secret value to inject for the domain. + - `url: string` - - `type: "code_interpreter"` + The URL of the source. - The type of the code interpreter tool. Always `code_interpreter`. + - `OpenPage object { type, url }` - - `"code_interpreter"` + Action type "open_page" - Opens a specific URL from search results. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `type: "open_page"` - The tool invocation context(s). + The action type. - - `"direct"` + - `"open_page"` - - `"programmatic"` + - `url: optional string` - - `ProgrammaticToolCalling object { type }` + The URL opened by the model. - - `type: "programmatic_tool_calling"` + - `FindInPage object { pattern, type, url }` - The type of the tool. Always `programmatic_tool_calling`. + Action type "find_in_page": Searches for a pattern within a loaded page. - - `"programmatic_tool_calling"` + - `pattern: string` - - `ImageGeneration object { type, action, background, 9 more }` + The pattern or text to search for within the page. - A tool that generates images using the GPT image models. + - `type: "find_in_page"` - - `type: "image_generation"` + The action type. - The type of the image generation tool. Always `image_generation`. + - `"find_in_page"` - - `"image_generation"` + - `url: string` - - `action: optional "generate" or "edit" or "auto"` + The URL of the page searched for the pattern. - Whether to generate a new image or edit an existing image. Default: `auto`. + - `status: "in_progress" or "searching" or "completed" or "failed"` - - `"generate"` + The status of the web search tool call. - - `"edit"` + - `"in_progress"` - - `"auto"` + - `"searching"` - - `background: optional "transparent" or "opaque" or "auto"` + - `"completed"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + - `"failed"` - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + - `type: "web_search_call"` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + The type of the web search tool call. Always `web_search_call`. - - `"transparent"` + - `"web_search_call"` - - `"opaque"` + - `agent: optional object { agent_name }` - - `"auto"` + The agent that produced this item. - - `input_fidelity: optional "high" or "low"` + - `agent_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 canonical name of the agent that produced this item. - - `"high"` + - `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. - - `input_image_mask: optional object { file_id, image_url }` + - `arguments: string` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + A JSON string of the arguments to pass to the function. - - `file_id: optional string` + - `call_id: string` - File ID for the mask image. + The unique ID of the function tool call generated by the model. - - `image_url: optional string` + - `name: string` - Base64-encoded mask image. + The name of the function to run. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `type: "function_call"` - The image generation model to use. Default: `gpt-image-1`. + The type of the function tool call. Always `function_call`. - - `string` + - `"function_call"` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `id: optional string` - The image generation model to use. Default: `gpt-image-1`. + The unique ID of the function tool call. - - `"gpt-image-1"` + - `agent: optional object { agent_name }` - - `"gpt-image-1-mini"` + The agent that produced this item. - - `"gpt-image-2"` + - `agent_name: string` - - `"gpt-image-2-2026-04-21"` + The canonical name of the agent that produced this item. - - `"gpt-image-1.5"` + - `caller: optional object { type } or object { caller_id, type }` - - `"chatgpt-image-latest"` + The execution context that produced this tool call. - - `moderation: optional "auto" or "low"` + - `Direct object { type }` - Moderation level for the generated image. Default: `auto`. + - `type: "direct"` - - `"auto"` + - `"direct"` - - `"low"` + - `Program object { caller_id, type }` - - `output_compression: optional number` + - `caller_id: string` - Compression level for the output image. Default: 100. + The call ID of the program item that produced this tool call. - - `output_format: optional "png" or "webp" or "jpeg"` + - `type: "program"` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `"program"` - - `"png"` + - `namespace: optional string` - - `"webp"` + The namespace of the function to run. - - `"jpeg"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `partial_images: optional number` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `"in_progress"` - - `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`. + - `"incomplete"` - - `"low"` + - `FunctionCallOutput object { call_id, output, type, 4 more }` - - `"medium"` + The output of a function tool call. - - `"high"` + - `call_id: string` - - `"auto"` + The unique ID of the function tool call generated by the model. - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `output: string or array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` - 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, image, or file output of the function tool call. - `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 + A JSON string of the output of the function tool call. - - `"container_auto"` + - `array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` - - `file_ids: optional array of string` + An array of content outputs (text, image, file) for the function tool call. - An optional list of uploaded files to make available to your code. + - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + A text input to the model. - The memory limit for the container. + - `text: string` - - `"1g"` + The text input to the model. - - `"4g"` + - `type: "input_text"` - - `"16g"` + The type of the input item. Always `input_text`. - - `"64g"` + - `"input_text"` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `prompt_cache_breakpoint: optional object { mode }` - Network access policy for the container. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `BetaContainerNetworkPolicyDisabled object { type }` + - `mode: "explicit"` - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + The breakpoint mode. Always `explicit`. - - `skills: optional array of BetaSkillReference or BetaInlineSkill` + - `"explicit"` - An optional list of skills referenced by id or inline data. + - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` - - `BetaSkillReference object { skill_id, type, version }` + An image input to the model. Learn about [image inputs](/docs/guides/vision) - - `skill_id: string` + - `type: "input_image"` - The ID of the referenced skill. + The type of the input item. Always `input_image`. - - `type: "skill_reference"` + - `"input_image"` - References a skill created with the /v1/skills endpoint. + - `detail: optional "low" or "high" or "auto" or "original"` - - `"skill_reference"` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `version: optional string` + - `"low"` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `"high"` - - `BetaInlineSkill object { description, name, source, type }` + - `"auto"` - - `description: string` + - `"original"` - The description of the skill. + - `file_id: optional string` - - `name: string` + The ID of the file to be sent to the model. - The name of the skill. + - `image_url: optional string` - - `source: BetaInlineSkillSource` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - Inline skill payload + - `prompt_cache_breakpoint: optional object { mode }` - - `data: 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. - Base64-encoded skill zip bundle. + - `mode: "explicit"` - - `media_type: "application/zip"` + The breakpoint mode. Always `explicit`. - The media type of the inline skill payload. Must be `application/zip`. + - `"explicit"` - - `"application/zip"` + - `BetaResponseInputFileContent object { type, detail, file_data, 4 more }` - - `type: "base64"` + A file input to the model. - The type of the inline skill source. Must be `base64`. + - `type: "input_file"` - - `"base64"` + The type of the input item. Always `input_file`. - - `type: "inline"` + - `"input_file"` - Defines an inline skill for this request. + - `detail: optional "auto" or "low" or "high"` - - `"inline"` + 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`. - - `BetaLocalEnvironment object { type, skills }` + - `"auto"` - - `type: "local"` + - `"low"` - Use a local computer environment. + - `"high"` - - `"local"` + - `file_data: optional string` - - `skills: optional array of BetaLocalSkill` + The base64-encoded data of the file to be sent to the model. - 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. + - `file_url: optional string` - - `name: string` + The URL of the file to be sent to the model. - The name of the skill. + - `filename: optional string` - - `path: string` + The name of the file to be sent to the model. - The path to the directory containing the skill. + - `prompt_cache_breakpoint: optional object { mode }` - - `BetaContainerReference object { container_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. - - `container_id: string` + - `mode: "explicit"` - The ID of the referenced container. + The breakpoint mode. Always `explicit`. - - `type: "container_reference"` + - `"explicit"` - References a container created with the /v1/containers endpoint + - `type: "function_call_output"` - - `"container_reference"` + 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](https://platform.openai.com/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 }` - - `Namespace object { description, name, tools, type }` + An image input to the model. Learn about [image inputs](/docs/guides/vision) - Groups function/custom tools under a shared namespace. + - `EncryptedContent object { encrypted_content, type }` - - `description: string` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - A description of the namespace shown to the model. + - `encrypted_content: string` - - `name: string` + Opaque encrypted content. - The namespace name used in tool calls (for example, `crm`). + - `type: "encrypted_content"` - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + The type of the input item. Always `encrypted_content`. - The function/custom tools available inside this namespace. + - `"encrypted_content"` - - `Function object { name, type, allowed_callers, 5 more }` + - `recipient: string` - - `name: string` + The destination agent identity. - - `type: "function"` + - `type: "agent_message"` - - `"function"` + 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 function should be deferred and discovered via tool search. + - `agent_name: string` - - `description: optional string` + The canonical name of the agent that produced this item. - - `output_schema: optional map[unknown]` + - `MultiAgentCall object { action, arguments, call_id, 3 more }` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `parameters: optional unknown` + The multi-agent action that was executed. - - `strict: optional boolean` + - `"spawn_agent"` - 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. + - `"interrupt_agent"` - - `Custom object { name, type, allowed_callers, 3 more }` + - `"list_agents"` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `"send_message"` - - `name: string` + - `"followup_task"` - The name of the custom tool, used to identify it in tool calls. + - `"wait_agent"` - - `type: "custom"` + - `arguments: string` - The type of the custom tool. Always `custom`. + The action arguments as a JSON string. - - `"custom"` + - `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"` - - `defer_loading: optional boolean` + - `id: optional string` - Whether this tool should be deferred and discovered via tool search. + The unique ID of this multi-agent call. - - `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 }` + - `MultiAgentCallOutput object { action, call_id, output, 3 more }` - Unconstrained free-form text. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `type: "text"` + The multi-agent action that produced this result. - Unconstrained text format. Always `text`. + - `"spawn_agent"` - - `"text"` + - `"interrupt_agent"` - - `Grammar object { definition, syntax, type }` + - `"list_agents"` - A grammar defined by the user. + - `"send_message"` - - `definition: string` + - `"followup_task"` - The grammar definition. + - `"wait_agent"` - - `syntax: "lark" or "regex"` + - `call_id: string` - The syntax of the grammar definition. One of `lark` or `regex`. + The unique ID of the multi-agent call. - - `"lark"` + - `output: array of object { text, type, annotations }` - - `"regex"` + Text output returned by the multi-agent action. - - `type: "grammar"` + - `text: string` - Grammar format. Always `grammar`. + The text content. - - `"grammar"` + - `type: "output_text"` - - `type: "namespace"` + The content type. Always `output_text`. - The type of the tool. Always `namespace`. + - `"output_text"` - - `"namespace"` + - `annotations: optional array of object { file_id, filename, index, type } or array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` - - `ToolSearch object { type, description, execution, parameters }` + Citations associated with the text content. - Hosted or BYOT tool search configuration for deferred tools. + - `array of object { file_id, filename, index, type }` - - `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 file cited. - 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_citation"` - - `"server"` + The citation type. Always `file_citation`. - - `"client"` + - `"file_citation"` - - `parameters: optional unknown` + - `array of object { end_index, start_index, title, 2 more }` - Parameter schema for a client-executed tool search tool. + - `end_index: number` - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + The index of the last character of the citation in the 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). + - `start_index: number` - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + The index of the first character of the citation in the message. - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `title: string` - - `"web_search_preview"` + The title of the cited resource. - - `"web_search_preview_2025_03_11"` + - `type: "url_citation"` - - `search_content_types: optional array of "text" or "image"` + The citation type. Always `url_citation`. - - `"text"` + - `"url_citation"` - - `"image"` + - `url: string` - - `search_context_size: optional "low" or "medium" or "high"` + The URL of the cited resource. - 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. + - `array of object { container_id, end_index, file_id, 3 more }` - - `"low"` + - `container_id: string` - - `"medium"` + The ID of the container. - - `"high"` + - `end_index: number` - - `user_location: optional object { type, city, country, 2 more }` + The index of the last character of the citation in the message. - The user's location. + - `file_id: string` - - `type: "approximate"` + The ID of the container file. - The type of location approximation. Always `approximate`. + - `filename: string` - - `"approximate"` + 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 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 citation type. Always `container_file_citation`. - - `region: optional string` + - `"container_file_citation"` - Free text input for the region of the user, e.g. `California`. + - `type: "multi_agent_call_output"` - - `timezone: optional string` + The item type. Always `multi_agent_call_output`. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `"multi_agent_call_output"` - - `ApplyPatch object { type, allowed_callers }` + - `id: optional string` - Allows the assistant to create, delete, or update files using unified diffs. + The unique ID of this multi-agent call output. - - `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). + - `ToolSearchCall object { arguments, type, id, 4 more }` - - `"direct"` + - `arguments: unknown` - - `"programmatic"` + The arguments supplied to the tool search call. - - `type: "tool_search_output"` + - `type: "tool_search_call"` - The item type. Always `tool_search_output`. + The item type. Always `tool_search_call`. - - `"tool_search_output"` + - `"tool_search_call"` - `id: optional string` - The unique ID of this tool search output. + The unique ID of this tool search call. - `agent: optional object { agent_name }` @@ -125286,7 +123706,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `status: optional "in_progress" or "completed" or "incomplete"` - The status of the tool search output. + The status of the tool search call. - `"in_progress"` @@ -125294,17 +123714,11 @@ 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"` + - `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` - A list of additional tools made available at this item. + The loaded tool definitions returned by the tool search output. - `Function object { name, parameters, strict, 5 more }` @@ -125567,7 +123981,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-web-search). + [web search tool](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -125627,7 +124041,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -125679,7 +124093,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -125825,8 +124239,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`. @@ -125871,19 +124317,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `background: optional "transparent" or "opaque" or "auto"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. - - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. - - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - `"transparent"` @@ -125912,13 +124347,13 @@ curl -X POST https://api.openai.com/v1/responses/compact \ Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `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-2" or 3 more` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` The image generation model to use. Default: `gpt-image-1`. @@ -125926,14 +124361,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"gpt-image-1-mini"` - - `"gpt-image-2"` - - - `"gpt-image-2-2026-04-21"` - - `"gpt-image-1.5"` - - `"chatgpt-image-latest"` - - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -126024,127 +124453,131 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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"` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `file_ids: optional array of string` - - `name: string` + An optional list of uploaded files to make available to your code. - The name of the custom tool, used to identify it in tool calls. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `type: "custom"` + The memory limit for the container. - The type of the custom tool. Always `custom`. + - `"1g"` - - `"custom"` + - `"4g"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"16g"` - The tool invocation context(s). + - `"64g"` - - `"direct"` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `"programmatic"` + Network access policy for the container. - - `defer_loading: optional boolean` + - `BetaContainerNetworkPolicyDisabled object { type }` - Whether this tool should be deferred and discovered via tool search. + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `description: optional string` + - `skills: optional array of BetaSkillReference or BetaInlineSkill` - Optional description of the custom tool, used to provide more context. + An optional list of skills referenced by id or inline data. - - `format: optional object { type } or object { definition, syntax, type }` + - `BetaSkillReference object { skill_id, type, version }` - The input format for the custom tool. Default is unconstrained text. + - `skill_id: string` - - `Text object { type }` + The ID of the referenced skill. - Unconstrained free-form text. + - `type: "skill_reference"` - - `type: "text"` + References a skill created with the /v1/skills endpoint. - Unconstrained text format. Always `text`. + - `"skill_reference"` - - `"text"` + - `version: optional string` - - `Grammar object { definition, syntax, type }` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - A grammar defined by the user. + - `BetaInlineSkill object { description, name, source, type }` - - `definition: string` + - `description: string` - The grammar definition. + The description of the skill. - - `syntax: "lark" or "regex"` + - `name: string` - The syntax of the grammar definition. One of `lark` or `regex`. + The name of the skill. - - `"lark"` + - `source: BetaInlineSkillSource` - - `"regex"` + Inline skill payload - - `type: "grammar"` + - `data: string` - Grammar format. Always `grammar`. + Base64-encoded skill zip bundle. - - `"grammar"` + - `media_type: "application/zip"` - - `Namespace object { description, name, tools, type }` + The media type of the inline skill payload. Must be `application/zip`. - Groups function/custom tools under a shared namespace. + - `"application/zip"` - - `description: string` + - `type: "base64"` - A description of the namespace shown to the model. + The type of the inline skill source. Must be `base64`. - - `name: string` + - `"base64"` - The namespace name used in tool calls (for example, `crm`). + - `type: "inline"` - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + Defines an inline skill for this request. - The function/custom tools available inside this namespace. + - `"inline"` - - `Function object { name, type, allowed_callers, 5 more }` + - `BetaLocalEnvironment object { type, skills }` - - `name: string` + - `type: "local"` - - `type: "function"` + Use a local computer environment. - - `"function"` + - `"local"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `skills: optional array of BetaLocalSkill` - The tool invocation context(s). + An optional list of skills. - - `"direct"` + - `description: string` - - `"programmatic"` + The description of the skill. - - `defer_loading: optional boolean` + - `name: string` - Whether this function should be deferred and discovered via tool search. + The name of the skill. - - `description: optional string` + - `path: string` - - `output_schema: optional map[unknown]` + The path to the directory containing the skill. - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `BetaContainerReference object { container_id, type }` - - `parameters: optional unknown` + - `container_id: string` - - `strict: optional boolean` + The ID of the referenced container. - 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: "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](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -126208,707 +124641,233 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"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 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](https://platform.openai.com/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 - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. - - - `status: optional "in_progress" or "completed" or "incomplete"` - - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `Compaction object { encrypted_content, type, id, agent }` - - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/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. + - `Namespace object { description, name, tools, type }` - - `caller: optional object { type } or object { caller_id, type }` + Groups function/custom tools under a shared namespace. - The execution context that produced this tool call. + - `description: string` - - `Direct object { type }` + A description of the namespace shown to the model. - - `type: "direct"` + - `name: string` - The caller type. Always `direct`. + The namespace name used in tool calls (for example, `crm`). - - `"direct"` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - - `Program object { caller_id, type }` + The function/custom tools available inside this namespace. - - `caller_id: string` + - `Function object { name, type, allowed_callers, 5 more }` - The call ID of the program item that produced this tool call. + - `name: string` - - `type: "program"` + - `type: "function"` - The caller type. Always `program`. + - `"function"` - - `"program"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `environment: optional BetaLocalEnvironment or BetaContainerReference` + The tool invocation context(s). - The environment to execute the shell commands in. + - `"direct"` - - `BetaLocalEnvironment object { type, skills }` + - `"programmatic"` - - `BetaContainerReference object { container_id, type }` + - `defer_loading: optional boolean` - - `status: optional "in_progress" or "completed" or "incomplete"` + Whether this function should be deferred and discovered via tool search. - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `description: optional string` - - `"in_progress"` + - `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. - - `"incomplete"` + - `parameters: optional unknown` - - `ShellCallOutput object { call_id, output, type, 5 more }` + - `strict: optional boolean` - The streamed output items emitted by a shell tool 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. - - `call_id: string` + - `Custom object { name, type, allowed_callers, 3 more }` - The unique ID of the shell tool call generated by the model. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `output: array of BetaResponseFunctionShellCallOutputContent` + - `name: string` - Captured chunks of stdout and stderr output, along with their associated outcomes. + The name of the custom tool, used to identify it in tool calls. - - `outcome: object { type } or object { exit_code, type }` + - `type: "custom"` - The exit or timeout outcome associated with this shell call. + The type of the custom tool. Always `custom`. - - `Timeout object { type }` + - `"custom"` - Indicates that the shell call exceeded its configured time limit. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `type: "timeout"` + The tool invocation context(s). - The outcome type. Always `timeout`. + - `"direct"` - - `"timeout"` + - `"programmatic"` - - `Exit object { exit_code, type }` + - `defer_loading: optional boolean` - Indicates that the shell commands finished and returned an exit code. + Whether this tool should be deferred and discovered via tool search. - - `exit_code: number` + - `description: optional string` - The exit code returned by the shell process. + Optional description of the custom tool, used to provide more context. - - `type: "exit"` + - `format: optional object { type } or object { definition, syntax, type }` - The outcome type. Always `exit`. + The input format for the custom tool. Default is unconstrained text. - - `"exit"` + - `Text object { type }` - - `stderr: string` + Unconstrained free-form text. - Captured stderr output for the shell call. + - `type: "text"` - - `stdout: string` + Unconstrained text format. Always `text`. - Captured stdout output for the shell call. + - `"text"` - - `type: "shell_call_output"` + - `Grammar object { definition, syntax, type }` - The type of the item. Always `shell_call_output`. + A grammar defined by the user. - - `"shell_call_output"` + - `definition: string` - - `id: optional string` + The grammar definition. - The unique ID of the shell tool call output. Populated when this item is returned via API. + - `syntax: "lark" or "regex"` - - `agent: optional object { agent_name }` + The syntax of the grammar definition. One of `lark` or `regex`. - The agent that produced this item. + - `"lark"` - - `agent_name: string` + - `"regex"` - The canonical name of the agent that produced this item. + - `type: "grammar"` - - `caller: optional object { type } or object { caller_id, type }` + Grammar format. Always `grammar`. - The execution context that produced this tool call. + - `"grammar"` - - `Direct object { type }` + - `type: "namespace"` - - `type: "direct"` + The type of the tool. Always `namespace`. - The caller type. Always `direct`. + - `"namespace"` - - `"direct"` + - `ToolSearch object { type, description, execution, parameters }` - - `Program object { caller_id, type }` + Hosted or BYOT tool search configuration for deferred tools. - - `caller_id: string` + - `type: "tool_search"` - The call ID of the program item that produced this tool call. + The type of the tool. Always `tool_search`. - - `type: "program"` + - `"tool_search"` - The caller type. Always `program`. + - `description: optional string` - - `"program"` + Description shown to the model for a client-executed tool search tool. - - `max_output_length: optional number` + - `execution: optional "server" or "client"` - The maximum number of UTF-8 characters captured for this shell call's combined output. + Whether tool search is executed by the server or by the client. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"server"` - The status of the shell call output. + - `"client"` - - `"in_progress"` + - `parameters: optional unknown` - - `"completed"` + Parameter schema for a client-executed tool search tool. - - `"incomplete"` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - - `ApplyPatchCall object { call_id, operation, status, 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). - A tool call representing a request to create, delete, or update files using diff patches. + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `call_id: string` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - The unique ID of the apply patch tool call generated by the model. + - `"web_search_preview"` - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + - `"web_search_preview_2025_03_11"` - The specific create, delete, or update instruction for the apply_patch tool call. + - `search_content_types: optional array of "text" or "image"` - - `CreateFile object { diff, path, type }` + - `"text"` - Instruction for creating a new file via the apply_patch tool. + - `"image"` - - `diff: string` + - `search_context_size: optional "low" or "medium" or "high"` - Unified diff content to apply when creating the 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. - - `path: string` + - `"low"` - Path of the file to create relative to the workspace root. + - `"medium"` - - `type: "create_file"` + - `"high"` - The operation type. Always `create_file`. + - `user_location: optional object { type, city, country, 2 more }` - - `"create_file"` + The user's location. - - `DeleteFile object { path, type }` + - `type: "approximate"` - Instruction for deleting an existing file via the apply_patch tool. + The type of location approximation. Always `approximate`. - - `path: string` + - `"approximate"` - Path of the file to delete relative to the workspace root. + - `city: optional string` - - `type: "delete_file"` + Free text input for the city of the user, e.g. `San Francisco`. - The operation type. Always `delete_file`. + - `country: optional string` - - `"delete_file"` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `UpdateFile object { diff, path, type }` + - `region: optional string` - Instruction for updating an existing 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 to the existing file. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `path: string` + - `ApplyPatch object { type, allowed_callers }` - Path of the file to update relative to the workspace root. + Allows the assistant to create, delete, or update files using unified diffs. - - `type: "update_file"` + - `type: "apply_patch"` - The operation type. Always `update_file`. + The type of the tool. Always `apply_patch`. - - `"update_file"` + - `"apply_patch"` - - `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"` + - `type: "tool_search_output"` - The type of the item. Always `apply_patch_call`. + The item type. Always `tool_search_output`. - - `"apply_patch_call"` + - `"tool_search_output"` - `id: optional string` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + The unique ID of this tool search output. - `agent: optional object { agent_name }` @@ -126918,1117 +124877,1133 @@ 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`. + - `call_id: optional string` - - `"direct"` + The unique ID of the tool search call generated by the model. - - `Program object { caller_id, type }` + - `execution: optional "server" or "client"` - - `caller_id: string` + Whether tool search was executed by the server or by the client. - The call ID of the program item that produced this tool call. + - `"server"` - - `type: "program"` + - `"client"` - The caller type. Always `program`. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"program"` + The status of the tool search output. - - `ApplyPatchCallOutput object { call_id, status, type, 4 more }` + - `"in_progress"` - The streamed output emitted by an apply patch tool call. + - `"completed"` - - `call_id: string` + - `"incomplete"` - The unique ID of the apply patch tool call generated by the model. + - `AdditionalTools object { role, tools, type, 2 more }` - - `status: "completed" or "failed"` + - `role: "developer"` - The status of the apply patch tool call output. One of `completed` or `failed`. + The role that provided the additional tools. Only `developer` is supported. - - `"completed"` + - `"developer"` - - `"failed"` + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - - `type: "apply_patch_call_output"` + A list of additional tools made available at this item. - The type of the item. Always `apply_patch_call_output`. + - `Function object { name, parameters, strict, 5 more }` - - `"apply_patch_call_output"` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `id: optional string` + - `name: string` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + The name of the function to call. - - `agent: optional object { agent_name }` + - `parameters: map[unknown]` - The agent that produced this item. + A JSON schema object describing the parameters of the function. - - `agent_name: string` + - `strict: boolean` - The canonical name of the agent that produced this item. + Whether strict parameter validation is enforced for this function tool. - - `caller: optional object { type } or object { caller_id, type }` + - `type: "function"` - The execution context that produced this tool call. + The type of the function tool. Always `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` - - The call ID of the program item that produced this tool call. - - - `type: "program"` + - `"programmatic"` - The caller type. Always `program`. + - `defer_loading: optional boolean` - - `"program"` + Whether this function is deferred and loaded via tool search. - - `output: optional string` + - `description: optional string` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + A description of the function. Used by the model to determine whether or not to call the function. - - `McpListTools object { id, server_label, tools, 3 more }` + - `output_schema: optional map[unknown]` - A list of tools available on an MCP server. + 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 list. + 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). - - `server_label: string` + - `type: "file_search"` - The label of the MCP server. + The type of the file search tool. Always `file_search`. - - `tools: array of object { input_schema, name, annotations, description }` + - `"file_search"` - The tools available on the server. + - `vector_store_ids: array of string` - - `input_schema: unknown` + The IDs of the vector stores to search. - The JSON schema describing the tool's input. + - `filters: optional object { key, type, value } or object { filters, type }` - - `name: string` + A filter to apply. - The name of the tool. + - `ComparisonFilter object { key, type, value }` - - `annotations: optional unknown` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - Additional annotations about the tool. + - `key: string` - - `description: optional string` + The key to compare against the value. - The description of the tool. + - `type: "eq" or "ne" or "gt" or 5 more` - - `type: "mcp_list_tools"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The type of the item. Always `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 - - `"mcp_list_tools"` + - `"eq"` - - `agent: optional object { agent_name }` + - `"ne"` - The agent that produced this item. + - `"gt"` - - `agent_name: string` + - `"gte"` - The canonical name of the agent that produced this item. + - `"lt"` - - `error: optional string` + - `"lte"` - Error message if the server could not list tools. + - `"in"` - - `McpApprovalRequest object { id, arguments, name, 3 more }` + - `"nin"` - A request for human approval of a tool invocation. + - `value: string or number or boolean or array of string or number` - - `id: string` + The value to compare against the attribute key; supports string, number, or boolean types. - The unique ID of the approval request. + - `string` - - `arguments: string` + - `number` - A JSON string of arguments for the tool. + - `boolean` - - `name: string` + - `array of string or number` - The name of the tool to run. + - `string` - - `server_label: string` + - `number` - The label of the MCP server making the request. + - `CompoundFilter object { filters, type }` - - `type: "mcp_approval_request"` + Combine multiple filters using `and` or `or`. - The type of the item. Always `mcp_approval_request`. + - `filters: array of object { key, type, value } or unknown` - - `"mcp_approval_request"` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `agent: optional object { agent_name }` + - `ComparisonFilter object { key, type, value }` - The agent that produced this item. + 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. - - `McpApprovalResponse object { approval_request_id, approve, type, 3 more }` + - `type: "eq" or "ne" or "gt" or 5 more` - A response to an MCP approval request. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `approval_request_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 approval request being answered. + - `"eq"` - - `approve: boolean` + - `"ne"` - Whether the request was approved. + - `"gt"` - - `type: "mcp_approval_response"` + - `"gte"` - The type of the item. Always `mcp_approval_response`. + - `"lt"` - - `"mcp_approval_response"` + - `"lte"` - - `id: optional string` + - `"in"` - The unique ID of the approval response + - `"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` - - `reason: optional string` + - `boolean` - Optional reason for the decision. + - `array of string or number` - - `McpCall object { id, arguments, name, 7 more }` + - `string` - An invocation of a tool on an MCP server. + - `number` - - `id: string` + - `unknown` - The unique ID of the tool call. + - `type: "and" or "or"` - - `arguments: string` + Type of operation: `and` or `or`. - A JSON string of the arguments passed to the tool. + - `"and"` - - `name: string` + - `"or"` - The name of the tool that was run. + - `max_num_results: optional number` - - `server_label: string` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - The label of the MCP server running the tool. + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `type: "mcp_call"` + Ranking options for search. - The type of the item. Always `mcp_call`. + - `hybrid_search: optional object { embedding_weight, text_weight }` - - `"mcp_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. - - `approval_request_id: optional string` + - `ranker: optional "auto" or "default-2024-11-15"` - 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 ranker to use for the file search. - - `error: optional string` + - `"auto"` - The error from the tool call, if any. + - `"default-2024-11-15"` - - `output: optional string` + - `score_threshold: optional number` - The output from the tool call. + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `Computer object { type }` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + 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"` - - `"calling"` + - `ComputerUsePreview object { display_height, display_width, environment, type }` - - `"failed"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `CustomToolCallOutput object { call_id, output, type, 3 more }` + - `display_height: number` - The output of a custom tool call from your code, being sent back to the model. + The height of the computer display. - - `call_id: string` + - `display_width: number` - The call ID, used to map this custom tool call output to a custom tool call. + The width of the computer display. - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `environment: "windows" or "mac" or "linux" or 2 more` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + The type of computer environment to control. - - `StringOutput = string` + - `"windows"` - A string of the output of the custom tool call. + - `"mac"` - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `"linux"` - Text, image, or file output of the custom tool call. + - `"ubuntu"` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `"browser"` - A text input to the model. + - `type: "computer_use_preview"` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + The type of the computer use tool. Always `computer_use_preview`. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `"computer_use_preview"` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `WebSearch object { type, filters, search_context_size, user_location }` - A file input to the model. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - - `type: "custom_tool_call_output"` + - `type: "web_search" or "web_search_2025_08_26"` - The type of the custom tool call output. Always `custom_tool_call_output`. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `"custom_tool_call_output"` + - `"web_search"` - - `id: optional string` + - `"web_search_2025_08_26"` - The unique ID of the custom tool call output in the OpenAI platform. + - `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` - - `CustomToolCall object { call_id, input, name, 5 more }` + Free text input for the region of the user, e.g. `California`. - A call to a custom tool created by the model. + - `timezone: optional string` - - `call_id: string` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - An identifier used to map this custom tool call to a tool call output. + - `type: optional "approximate"` - - `input: string` + The type of location approximation. Always `approximate`. - The input for the custom tool call generated by the model. + - `"approximate"` - - `name: string` + - `Mcp object { server_label, type, allowed_callers, 9 more }` - The name of the custom tool being called. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - - `type: "custom_tool_call"` + - `server_label: string` - The type of the custom tool call. Always `custom_tool_call`. + A label for this MCP server, used to identify it in tool calls. - - `"custom_tool_call"` + - `type: "mcp"` - - `id: optional string` + The type of the MCP tool. Always `mcp`. - The unique ID of the custom tool call in the OpenAI platform. + - `"mcp"` - - `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 }` + - `allowed_tools: optional array of string or object { read_only, tool_names }` - The execution context that produced this tool call. + List of allowed tool names or a filter object. - - `Direct object { type }` + - `McpAllowedTools = array of string` - - `type: "direct"` + A string array of allowed tool names - - `"direct"` + - `McpToolFilter 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. - - `namespace: optional string` + - `authorization: optional string` - The namespace of the custom tool being called. + 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. - - `CompactionTrigger object { type, agent }` + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - Compacts the current context. Must be the final input 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). - - `type: "compaction_trigger"` + Currently supported `connector_id` values are: - The type of the item. Always `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` - - `"compaction_trigger"` + - `"connector_dropbox"` - - `agent: optional object { agent_name }` + - `"connector_gmail"` - The agent that produced this item. + - `"connector_googlecalendar"` - - `agent_name: string` + - `"connector_googledrive"` - The canonical name of the agent that produced this item. + - `"connector_microsoftteams"` - - `ItemReference object { id, agent, type }` + - `"connector_outlookcalendar"` - An internal identifier for an item to reference. + - `"connector_outlookemail"` - - `id: string` + - `"connector_sharepoint"` - The ID of the item to reference. + - `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"` - - `type: optional "item_reference"` + Specify which of the MCP server's tools require approval. - The type of item to reference. Always `item_reference`. + - `McpToolApprovalFilter object { always, never }` - - `"item_reference"` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `Program object { id, call_id, code, 3 more }` + - `always: optional object { read_only, tool_names }` - - `id: string` + A filter object to specify which tools are allowed. - The unique ID of this program item. + - `read_only: optional boolean` - - `call_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 stable call ID of the program item. + - `tool_names: optional array of string` - - `code: string` + List of allowed tool names. - The JavaScript source executed by programmatic tool calling. + - `never: optional object { read_only, tool_names }` - - `fingerprint: string` + A filter object to specify which tools are allowed. - Opaque program replay fingerprint that must be round-tripped. + - `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. - The item type. Always `program`. + - `tool_names: optional array of string` - - `"program"` + List of allowed tool names. - - `agent: optional object { agent_name }` + - `McpToolApprovalSetting = "always" or "never"` - 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. - - `agent_name: string` + - `"always"` - The canonical name of the agent that produced this item. + - `"never"` - - `ProgramOutput object { id, call_id, result, 3 more }` + - `server_description: optional string` - - `id: string` + Optional description of the MCP server, used to provide more context. - The unique ID of this program output item. + - `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 call ID of the program item. + - `tunnel_id: optional string` - - `result: 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 result produced by the program item. + - `CodeInterpreter object { container, type, allowed_callers }` - - `status: "completed" or "incomplete"` + A tool that runs Python code to help generate a response to a prompt. - The terminal status of the program output. + - `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: "program_output"` + The container ID. - The item type. Always `program_output`. + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - - `"program_output"` + 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` - - `metadata: map[string]` + An optional list of uploaded files to make available to your code. - 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. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The memory limit for the code interpreter container. - - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` + - `"1g"` - 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](https://platform.openai.com/docs/models) - to browse and compare available models. + - `"4g"` - - `"gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more` + - `"16g"` - 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](https://platform.openai.com/docs/models) - to browse and compare available models. + - `"64g"` - - `"gpt-5.6-sol"` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `"gpt-5.6-terra"` + Network access policy for the container. - - `"gpt-5.6-luna"` + - `BetaContainerNetworkPolicyDisabled object { type }` - - `"gpt-5.4"` + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `"gpt-5.4-mini"` + - `type: "code_interpreter"` - - `"gpt-5.4-nano"` + The type of the code interpreter tool. Always `code_interpreter`. - - `"gpt-5.4-mini-2026-03-17"` + - `"code_interpreter"` - - `"gpt-5.4-nano-2026-03-17"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"gpt-5.3-chat-latest"` + The tool invocation context(s). - - `"gpt-5.2"` + - `"direct"` - - `"gpt-5.2-2025-12-11"` + - `"programmatic"` - - `"gpt-5.2-chat-latest"` + - `ProgrammaticToolCalling object { type }` - - `"gpt-5.2-pro"` + - `type: "programmatic_tool_calling"` - - `"gpt-5.2-pro-2025-12-11"` + The type of the tool. Always `programmatic_tool_calling`. - - `"gpt-5.1"` + - `"programmatic_tool_calling"` - - `"gpt-5.1-2025-11-13"` + - `ImageGeneration object { type, action, background, 9 more }` - - `"gpt-5.1-codex"` + A tool that generates images using the GPT image models. - - `"gpt-5.1-mini"` + - `type: "image_generation"` - - `"gpt-5.1-chat-latest"` + The type of the image generation tool. Always `image_generation`. - - `"gpt-5"` + - `"image_generation"` - - `"gpt-5-mini"` + - `action: optional "generate" or "edit" or "auto"` - - `"gpt-5-nano"` + Whether to generate a new image or edit an existing image. Default: `auto`. - - `"gpt-5-2025-08-07"` + - `"generate"` - - `"gpt-5-mini-2025-08-07"` + - `"edit"` - - `"gpt-5-nano-2025-08-07"` + - `"auto"` - - `"gpt-5-chat-latest"` + - `background: optional "transparent" or "opaque" or "auto"` - - `"gpt-4.1"` + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - - `"gpt-4.1-mini"` + - `"transparent"` - - `"gpt-4.1-nano"` + - `"opaque"` - - `"gpt-4.1-2025-04-14"` + - `"auto"` - - `"gpt-4.1-mini-2025-04-14"` + - `input_fidelity: optional "high" or "low"` - - `"gpt-4.1-nano-2025-04-14"` + 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`. - - `"o4-mini"` + - `"high"` - - `"o4-mini-2025-04-16"` + - `"low"` - - `"o3"` + - `input_image_mask: optional object { file_id, image_url }` - - `"o3-2025-04-16"` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `"o3-mini"` + - `file_id: optional string` - - `"o3-mini-2025-01-31"` + File ID for the mask image. - - `"o1"` + - `image_url: optional string` - - `"o1-2024-12-17"` + Base64-encoded mask image. - - `"o1-preview"` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `"o1-preview-2024-09-12"` + The image generation model to use. Default: `gpt-image-1`. - - `"o1-mini"` + - `string` - - `"o1-mini-2024-09-12"` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `"gpt-4o"` + The image generation model to use. Default: `gpt-image-1`. - - `"gpt-4o-2024-11-20"` + - `"gpt-image-1"` - - `"gpt-4o-2024-08-06"` + - `"gpt-image-1-mini"` - - `"gpt-4o-2024-05-13"` + - `"gpt-image-1.5"` - - `"gpt-4o-audio-preview"` + - `moderation: optional "auto" or "low"` - - `"gpt-4o-audio-preview-2024-10-01"` + Moderation level for the generated image. Default: `auto`. - - `"gpt-4o-audio-preview-2024-12-17"` + - `"auto"` - - `"gpt-4o-audio-preview-2025-06-03"` + - `"low"` - - `"gpt-4o-mini-audio-preview"` + - `output_compression: optional number` - - `"gpt-4o-mini-audio-preview-2024-12-17"` + Compression level for the output image. Default: 100. - - `"gpt-4o-search-preview"` + - `output_format: optional "png" or "webp" or "jpeg"` - - `"gpt-4o-mini-search-preview"` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `"gpt-4o-search-preview-2025-03-11"` + - `"png"` - - `"gpt-4o-mini-search-preview-2025-03-11"` + - `"webp"` - - `"chatgpt-4o-latest"` + - `"jpeg"` - - `"codex-mini-latest"` + - `partial_images: optional number` - - `"gpt-4o-mini"` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `"gpt-4o-mini-2024-07-18"` + - `quality: optional "low" or "medium" or "high" or "auto"` - - `"gpt-4-turbo"` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `"gpt-4-turbo-2024-04-09"` + - `"low"` - - `"gpt-4-0125-preview"` + - `"medium"` - - `"gpt-4-turbo-preview"` + - `"high"` - - `"gpt-4-1106-preview"` + - `"auto"` - - `"gpt-4-vision-preview"` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `"gpt-4"` + 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-4-0314"` + - `string` - - `"gpt-4-0613"` + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `"gpt-4-32k"` + 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-4-32k-0314"` + - `"1024x1024"` - - `"gpt-4-32k-0613"` + - `"1024x1536"` - - `"gpt-3.5-turbo"` + - `"1536x1024"` - - `"gpt-3.5-turbo-16k"` + - `"auto"` - - `"gpt-3.5-turbo-0301"` + - `LocalShell object { type }` - - `"gpt-3.5-turbo-0613"` + A tool that allows the model to execute shell commands in a local environment. - - `"gpt-3.5-turbo-1106"` + - `type: "local_shell"` - - `"gpt-3.5-turbo-0125"` + The type of the local shell tool. Always `local_shell`. - - `"gpt-3.5-turbo-16k-0613"` + - `"local_shell"` - - `"o1-pro"` + - `Shell object { type, allowed_callers, environment }` - - `"o1-pro-2025-03-19"` + A tool that allows the model to execute shell commands. - - `"o3-pro"` + - `type: "shell"` - - `"o3-pro-2025-06-10"` + The type of the shell tool. Always `shell`. - - `"o3-deep-research"` + - `"shell"` - - `"o3-deep-research-2025-06-26"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"o4-mini-deep-research"` + The tool invocation context(s). - - `"o4-mini-deep-research-2025-06-26"` + - `"direct"` - - `"computer-use-preview"` + - `"programmatic"` - - `"computer-use-preview-2025-03-11"` + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - `"gpt-5-codex"` + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - - `"gpt-5-pro"` + - `BetaLocalEnvironment object { type, skills }` - - `"gpt-5-pro-2025-10-06"` + - `BetaContainerReference object { container_id, type }` - - `"gpt-5.1-codex-max"` + - `Custom object { name, type, allowed_callers, 3 more }` - - `string` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `object: "response"` + - `name: string` - The object type of this resource - always set to `response`. + The name of the custom tool, used to identify it in tool calls. - - `"response"` + - `type: "custom"` - - `output: array of BetaResponseOutputItem` + The type of the custom tool. Always `custom`. - An array of content items generated by the model. + - `"custom"` - - 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. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `BetaResponseOutputMessage object { id, content, role, 4 more }` + The tool invocation context(s). - An output message from the model. + - `"direct"` - - `FileSearchCall object { id, queries, status, 3 more }` + - `"programmatic"` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `defer_loading: optional boolean` - - `id: string` + Whether this tool should be deferred and discovered via tool search. - The unique ID of the file search tool call. + - `description: optional string` - - `queries: array of string` + Optional description of the custom tool, used to provide more context. - The queries used to search for files. + - `format: optional object { type } or object { definition, syntax, type }` - - `status: "in_progress" or "searching" or "completed" or 2 more` + The input format for the custom tool. Default is unconstrained text. - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `Text object { type }` - - `"in_progress"` + Unconstrained free-form text. - - `"searching"` + - `type: "text"` - - `"completed"` + Unconstrained text format. Always `text`. - - `"incomplete"` + - `"text"` - - `"failed"` + - `Grammar object { definition, syntax, type }` - - `type: "file_search_call"` + A grammar defined by the user. - The type of the file search tool call. Always `file_search_call`. + - `definition: string` - - `"file_search_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"` - - `results: optional array of object { attributes, file_id, filename, 2 more }` + - `type: "grammar"` - The results of the file search tool call. + Grammar format. Always `grammar`. - - `attributes: optional map[string or number or boolean]` + - `"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. Keys are strings - with a maximum length of 64 characters. Values are strings with a maximum - length of 512 characters, booleans, or numbers. + - `Namespace object { description, name, tools, type }` - - `string` + Groups function/custom tools under a shared namespace. - - `number` + - `description: string` - - `boolean` + A description of the namespace shown to the model. - - `file_id: optional string` + - `name: string` - The unique ID of the file. + The namespace name used in tool calls (for example, `crm`). - - `filename: optional string` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - The name of the file. + The function/custom tools available inside this namespace. - - `score: optional number` + - `Function object { name, type, allowed_callers, 5 more }` - The relevance score of the file - a value between 0 and 1. + - `name: string` - - `text: optional string` + - `type: "function"` - The text that was retrieved from the file. + - `"function"` - - `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](https://platform.openai.com/docs/guides/function-calling) for more information. + The tool invocation context(s). - - `arguments: string` + - `"direct"` - A JSON string of the arguments to pass to the function. + - `"programmatic"` - - `call_id: string` + - `defer_loading: optional boolean` - The unique ID of the function tool call generated by the model. + Whether this function should be deferred and discovered via tool search. - - `name: string` + - `description: optional string` - The name of the function to run. + - `output_schema: optional map[unknown]` - - `type: "function_call"` + 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 function tool call. Always `function_call`. + - `parameters: optional unknown` - - `"function_call"` + - `strict: optional boolean` - - `id: 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 unique ID of the function tool 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"` - - `caller: optional object { type } or object { caller_id, type }` + The type of the custom tool. Always `custom`. - The execution context that produced this tool call. + - `"custom"` - - `Direct object { type }` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `type: "direct"` + The tool invocation context(s). - `"direct"` - - `Program object { caller_id, type }` + - `"programmatic"` - - `caller_id: string` + - `defer_loading: optional boolean` - The call ID of the program item that produced this tool call. + Whether this tool should be deferred and discovered via tool search. - - `type: "program"` + - `description: optional string` - - `"program"` + Optional description of the custom tool, used to provide more context. - - `namespace: optional string` + - `format: optional object { type } or object { definition, syntax, type }` - The namespace of the function to run. + The input format for the custom tool. Default is unconstrained text. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `Text object { type }` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Unconstrained free-form text. - - `"in_progress"` + - `type: "text"` - - `"completed"` + Unconstrained text format. Always `text`. - - `"incomplete"` + - `"text"` - - `FunctionCallOutput object { id, call_id, output, 5 more }` + - `Grammar object { definition, syntax, type }` - - `id: string` + A grammar defined by the user. - The unique ID of the function call tool output. + - `definition: string` - - `call_id: string` + The grammar definition. - The unique ID of the function tool call generated by the model. + - `syntax: "lark" or "regex"` - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + The syntax of the grammar definition. One of `lark` or `regex`. - The output from the function call generated by your code. - Can be a string or an list of output content. + - `"lark"` - - `StringOutput = string` + - `"regex"` - A string of the output of the function call. + - `type: "grammar"` - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + Grammar format. Always `grammar`. - Text, image, or file output of the function call. + - `"grammar"` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `type: "namespace"` - A text input to the model. + The type of the tool. Always `namespace`. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `"namespace"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `ToolSearch object { type, description, execution, parameters }` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + Hosted or BYOT tool search configuration for deferred tools. - A file input to the model. + - `type: "tool_search"` - - `status: "in_progress" or "completed" or "incomplete"` + The type of the tool. Always `tool_search`. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"tool_search"` - - `"in_progress"` + - `description: optional string` - - `"completed"` + Description shown to the model for a client-executed tool search tool. - - `"incomplete"` + - `execution: optional "server" or "client"` - - `type: "function_call_output"` + Whether tool search is executed by the server or by the client. - The type of the function tool call output. Always `function_call_output`. + - `"server"` - - `"function_call_output"` + - `"client"` - - `agent: optional object { agent_name }` + - `parameters: optional unknown` - The agent that produced this item. + Parameter schema for a client-executed tool search tool. - - `agent_name: string` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - The canonical name of 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). - - `caller: optional object { type } or object { caller_id, type }` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - The execution context that produced this tool call. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `Direct object { type }` + - `"web_search_preview"` - - `type: "direct"` + - `"web_search_preview_2025_03_11"` - The caller type. Always `direct`. + - `search_content_types: optional array of "text" or "image"` - - `"direct"` + - `"text"` - - `Program object { caller_id, type }` + - `"image"` - - `caller_id: string` + - `search_context_size: optional "low" or "medium" or "high"` - The call ID of the program item that produced this tool call. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `type: "program"` + - `"low"` - The caller type. Always `program`. + - `"medium"` - - `"program"` + - `"high"` - - `created_by: optional string` + - `user_location: optional object { type, city, country, 2 more }` - The identifier of the actor that created the item. + The user's location. - - `AgentMessage object { id, author, content, 3 more }` + - `type: "approximate"` - - `id: string` + The type of location approximation. Always `approximate`. - The unique ID of the agent message. + - `"approximate"` - - `author: string` + - `city: optional string` - The sending agent identity. + Free text input for the city of the user, e.g. `San Francisco`. - - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` + - `country: optional string` - Encrypted content sent between agents. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `region: optional string` - A text input to the model. + Free text input for the region of the user, e.g. `California`. - - `BetaResponseOutputText object { annotations, text, type, logprobs }` + - `timezone: optional string` - A text output from the model. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `Text object { text, type }` + - `ApplyPatch object { type, allowed_callers }` - A text content. + Allows the assistant to create, delete, or update files using unified diffs. - - `text: string` + - `type: "apply_patch"` - - `type: "text"` + The type of the tool. Always `apply_patch`. - - `"text"` + - `"apply_patch"` - - `SummaryText object { text, type }` + - `allowed_callers: optional array of "direct" or "programmatic"` - A summary text from the model. + The tool invocation context(s). - - `text: string` + - `"direct"` - A summary of the reasoning output from the model so far. + - `"programmatic"` - - `type: "summary_text"` + - `type: "additional_tools"` - The type of the object. Always `summary_text`. + The item type. Always `additional_tools`. - - `"summary_text"` + - `"additional_tools"` - - `ReasoningText object { text, type }` + - `id: optional string` - Reasoning text from the model. + The unique ID of this additional tools item. - - `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"` + - `Reasoning object { id, summary, type, 4 more }` - - `BetaResponseOutputRefusal object { refusal, 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). - A refusal from 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](https://platform.openai.com/docs/guides/vision). + - `summary: array of object { text, type }` - - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` + Reasoning summary content. - A screenshot of a computer. + - `text: string` - - `detail: "low" or "high" or "auto" or "original"` + A summary of the reasoning output from the model so far. - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `type: "summary_text"` - - `"low"` + The type of the object. Always `summary_text`. - - `"high"` + - `"summary_text"` - - `"auto"` + - `type: "reasoning"` - - `"original"` + The type of the object. Always `reasoning`. - - `file_id: string` + - `"reasoning"` - The identifier of an uploaded file that contains the screenshot. + - `agent: optional object { agent_name }` - - `image_url: string` + The agent that produced this item. - The URL of the screenshot image. + - `agent_name: string` - - `type: "computer_screenshot"` + The canonical name of the agent that produced this item. - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + - `content: optional array of object { text, type }` - - `"computer_screenshot"` + Reasoning text content. - - `prompt_cache_breakpoint: optional object { mode }` + - `text: 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 reasoning text from the model. - - `mode: "explicit"` + - `type: "reasoning_text"` - The breakpoint mode. Always `explicit`. + The type of the reasoning text. Always `reasoning_text`. - - `"explicit"` + - `"reasoning_text"` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `encrypted_content: optional string` - A file input to the model. + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - - `EncryptedContent object { encrypted_content, type }` + - `status: optional "in_progress" or "completed" or "incomplete"` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `encrypted_content: string` + - `"in_progress"` - Opaque encrypted content. + - `"completed"` - - `type: "encrypted_content"` + - `"incomplete"` - The type of the input item. Always `encrypted_content`. + - `Compaction object { encrypted_content, type, id, agent }` - - `"encrypted_content"` + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). - - `recipient: string` + - `encrypted_content: string` - The destination agent identity. + The encrypted content of the compaction summary. - - `type: "agent_message"` + - `type: "compaction"` - The type of the item. Always `agent_message`. + The type of the item. Always `compaction`. - - `"agent_message"` + - `"compaction"` + + - `id: optional string` + + The ID of the compaction item. - `agent: optional object { agent_name }` @@ -128038,41 +126013,35 @@ curl -X POST https://api.openai.com/v1/responses/compact \ 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` + - `ImageGenerationCall object { id, result, status, 2 more }` - The multi-agent action to execute. + 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 JSON string of arguments generated for the action. + - `"completed"` - - `call_id: string` + - `"generating"` - The unique ID linking this call to its output. + - `"failed"` - - `type: "multi_agent_call"` + - `type: "image_generation_call"` - The type of the multi-agent call. Always `multi_agent_call`. + The type of the image generation call. Always `image_generation_call`. - - `"multi_agent_call"` + - `"image_generation_call"` - `agent: optional object { agent_name }` @@ -128082,159 +126051,166 @@ 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 }` + - `CodeInterpreterCall object { id, code, container_id, 4 more }` + + A tool call to run code. - `id: string` - The unique ID of the multi-agent call output item. + The unique ID of the code interpreter tool call. - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `code: string` - The multi-agent action that produced this result. + The code to run, or null if not available. - - `"spawn_agent"` + - `container_id: string` - - `"interrupt_agent"` + The ID of the container used to run the code. - - `"list_agents"` + - `outputs: array of object { logs, type } or object { type, url }` - - `"send_message"` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `"followup_task"` + - `Logs object { logs, type }` - - `"wait_agent"` + The logs output from the code interpreter. - - `call_id: string` + - `logs: string` - The unique ID of the multi-agent call. + The logs output from the code interpreter. - - `output: array of BetaResponseOutputText` + - `type: "logs"` - Text output returned by the multi-agent action. + The type of the output. Always `logs`. - - `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 }` + - `"logs"` - The annotations of the text output. + - `Image object { type, url }` - - `text: string` + The image output from the code interpreter. - The text output from the model. + - `type: "image"` - - `type: "output_text"` + The type of the output. Always `image`. - The type of the output text. Always `output_text`. + - `"image"` - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + - `url: string` - - `type: "multi_agent_call_output"` + The URL of the image output from the code interpreter. - The type of the multi-agent result. Always `multi_agent_call_output`. + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - - `"multi_agent_call_output"` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `agent: optional object { agent_name }` + - `"in_progress"` - The agent that produced this item. + - `"completed"` - - `agent_name: string` + - `"incomplete"` - The canonical name of the agent that produced this item. + - `"interpreting"` - - `WebSearchCall object { id, action, status, 2 more }` + - `"failed"` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `type: "code_interpreter_call"` - - `id: string` + The type of the code interpreter tool call. Always `code_interpreter_call`. - The unique ID of the web search tool call. + - `"code_interpreter_call"` - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + - `agent: optional object { agent_name }` - 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 agent that produced this item. - - `Search object { type, queries, query, sources }` + - `agent_name: string` - Action type "search" - Performs a web search query. + The canonical name of the agent that produced this item. - - `type: "search"` + - `LocalShellCall object { id, action, call_id, 3 more }` - The action type. + A tool call to run a command on the local shell. - - `"search"` + - `id: string` - - `queries: optional array of string` + The unique ID of the local shell call. - The search queries. + - `action: object { command, env, type, 3 more }` - - `query: optional string` + Execute a shell command on the server. - The search query. + - `command: array of string` - - `sources: optional array of object { type, url }` + The command to run. - The sources used in the search. + - `env: map[string]` - - `type: "url"` + Environment variables to set for the command. - The type of source. Always `url`. + - `type: "exec"` - - `"url"` + The type of the local shell action. Always `exec`. - - `url: string` + - `"exec"` - The URL of the source. + - `timeout_ms: optional number` - - `OpenPage object { type, url }` + Optional timeout in milliseconds for the command. - Action type "open_page" - Opens a specific URL from search results. + - `user: optional string` - - `type: "open_page"` + Optional user to run the command as. - The action type. + - `working_directory: optional string` - - `"open_page"` + Optional working directory to run the command in. - - `url: optional string` + - `call_id: string` - The URL opened by the model. + The unique ID of the local shell tool call generated by the model. - - `FindInPage object { pattern, type, url }` + - `status: "in_progress" or "completed" or "incomplete"` - Action type "find_in_page": Searches for a pattern within a loaded page. + The status of the local shell call. - - `pattern: string` + - `"in_progress"` - The pattern or text to search for within the page. + - `"completed"` - - `type: "find_in_page"` + - `"incomplete"` - The action type. + - `type: "local_shell_call"` - - `"find_in_page"` + The type of the local shell call. Always `local_shell_call`. - - `url: string` + - `"local_shell_call"` - The URL of the page searched for the pattern. + - `agent: optional object { agent_name }` - - `status: "in_progress" or "searching" or "completed" or "failed"` + The agent that produced this item. - The status of the web search tool call. + - `agent_name: string` - - `"in_progress"` + The canonical name of the agent that produced this item. - - `"searching"` + - `LocalShellCallOutput object { id, output, type, 2 more }` - - `"completed"` + The output of a local shell tool call. - - `"failed"` + - `id: string` - - `type: "web_search_call"` + The unique ID of the local shell tool call generated by the model. - The type of the web search tool call. Always `web_search_call`. + - `output: string` - - `"web_search_call"` + 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 }` @@ -128244,60 +126220,49 @@ 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 }` - - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - - - `id: string` - - The unique ID of the computer call. - - - `call_id: string` + - `status: optional "in_progress" or "completed" or "incomplete"` - An identifier used when responding to the tool call with output. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `pending_safety_checks: array of object { id, code, message }` + - `"in_progress"` - The pending safety checks for the computer call. + - `"completed"` - - `id: string` + - `"incomplete"` - The ID of the pending safety check. + - `ShellCall object { action, call_id, type, 5 more }` - - `code: optional string` + A tool representing a request to execute one or more shell commands. - The type of the pending safety check. + - `action: object { commands, max_output_length, timeout_ms }` - - `message: optional string` + The shell commands and limits that describe how to run the tool call. - Details about the pending safety check. + - `commands: array of string` - - `status: "in_progress" or "completed" or "incomplete"` + Ordered shell commands for the execution environment to run. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `max_output_length: optional number` - - `"in_progress"` + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - - `"completed"` + - `timeout_ms: optional number` - - `"incomplete"` + Maximum wall-clock time in milliseconds to allow the shell commands to run. - - `type: "computer_call"` + - `call_id: string` - The type of the computer call. Always `computer_call`. + The unique ID of the shell tool call generated by the model. - - `"computer_call"` + - `type: "shell_call"` - - `action: optional BetaComputerAction` + The type of the item. Always `shell_call`. - A click action. + - `"shell_call"` - - `actions: optional BetaComputerActionList` + - `id: optional string` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + The unique ID of the shell tool call. Populated when this item is returned via API. - `agent: optional object { agent_name }` @@ -128307,98 +126272,105 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `ComputerCallOutput object { id, call_id, output, 5 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 computer call tool output. + - `Direct object { type }` - - `call_id: string` + - `type: "direct"` - The ID of the computer tool call that produced the output. + The caller type. Always `direct`. - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `"direct"` - A computer screenshot image used with the computer use tool. + - `Program object { caller_id, type }` - - `status: "completed" or "incomplete" or "failed" or "in_progress"` + - `caller_id: string` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + The call ID of the program item that produced this tool call. - - `"completed"` + - `type: "program"` - - `"incomplete"` + The caller type. Always `program`. - - `"failed"` + - `"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"` - - `type: "computer_call_output"` + - `"completed"` - The type of the computer tool call output. Always `computer_call_output`. + - `"incomplete"` - - `"computer_call_output"` + - `ShellCallOutput object { call_id, output, type, 5 more }` - - `acknowledged_safety_checks: optional array of object { id, code, message }` + The streamed output items emitted by a shell tool call. - The safety checks reported by the API that have been acknowledged by the - developer. + - `call_id: string` - - `id: string` + The unique ID of the shell tool call generated by the model. - The ID of the pending safety check. + - `output: array of BetaResponseFunctionShellCallOutputContent` - - `code: optional string` + Captured chunks of stdout and stderr output, along with their associated outcomes. - The type of the pending safety check. + - `outcome: object { type } or object { exit_code, type }` - - `message: optional string` + The exit or timeout outcome associated with this shell call. - Details about the pending safety check. + - `Timeout object { type }` - - `agent: optional object { agent_name }` + Indicates that the shell call exceeded its configured time limit. - The agent that produced this item. + - `type: "timeout"` - - `agent_name: string` + The outcome type. Always `timeout`. - The canonical name of the agent that produced this item. + - `"timeout"` - - `created_by: optional string` + - `Exit object { exit_code, type }` - The identifier of the actor that created the item. + Indicates that the shell commands finished and returned an exit code. - - `Reasoning object { id, summary, type, 4 more }` + - `exit_code: number` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + The exit code returned by the shell process. - - `id: string` + - `type: "exit"` - The unique identifier of the reasoning content. + The outcome type. Always `exit`. - - `summary: array of object { text, type }` + - `"exit"` - Reasoning summary content. + - `stderr: string` - - `text: string` + Captured stderr output for the shell call. - A summary of the reasoning output from the model so far. + - `stdout: string` - - `type: "summary_text"` + Captured stdout output for the shell call. - The type of the object. Always `summary_text`. + - `type: "shell_call_output"` - - `"summary_text"` + The type of the item. Always `shell_call_output`. - - `type: "reasoning"` + - `"shell_call_output"` - The type of the object. Always `reasoning`. + - `id: optional string` - - `"reasoning"` + The unique ID of the shell tool call output. Populated when this item is returned via API. - `agent: optional object { agent_name }` @@ -128408,29 +126380,37 @@ 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 - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + 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 item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The status of the shell call output. - `"in_progress"` @@ -128438,3382 +126418,3307 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"incomplete"` - - `Program object { id, call_id, code, 3 more }` - - - `id: string` + - `ApplyPatchCall object { call_id, operation, status, 4 more }` - The unique ID of the program item. + A tool call representing a request to create, delete, or update files using diff patches. - `call_id: string` - The stable call ID of the program item. + The unique ID of the apply patch tool call generated by the model. - - `code: string` + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - The JavaScript source executed by programmatic tool calling. + The specific create, delete, or update instruction for the apply_patch tool call. - - `fingerprint: string` + - `CreateFile object { diff, path, type }` - Opaque program replay fingerprint that must be round-tripped. + Instruction for creating a new file via the apply_patch tool. - - `type: "program"` + - `diff: string` - The type of the item. Always `program`. + Unified diff content to apply when creating the file. - - `"program"` + - `path: string` - - `agent: optional object { agent_name }` + Path of the file to create relative to the workspace root. - The agent that produced this item. + - `type: "create_file"` - - `agent_name: string` + The operation type. Always `create_file`. - The canonical name of the agent that produced this item. + - `"create_file"` - - `ProgramOutput object { id, call_id, result, 3 more }` + - `DeleteFile object { path, type }` - - `id: string` + Instruction for deleting an existing file via the apply_patch tool. - The unique ID of the program output item. + - `path: string` - - `call_id: string` + Path of the file to delete relative to the workspace root. - The call ID of the program item. + - `type: "delete_file"` - - `result: string` + The operation type. Always `delete_file`. - The result produced by the program item. + - `"delete_file"` - - `status: "completed" or "incomplete"` + - `UpdateFile object { diff, path, type }` - The terminal status of the program output item. + Instruction for updating an existing file via the apply_patch tool. - - `"completed"` + - `diff: string` - - `"incomplete"` + Unified diff content to apply to the existing file. - - `type: "program_output"` + - `path: string` - The type of the item. Always `program_output`. + Path of the file to update relative to the workspace root. - - `"program_output"` + - `type: "update_file"` - - `agent: optional object { agent_name }` + The operation type. Always `update_file`. - The agent that produced this item. + - `"update_file"` - - `agent_name: string` + - `status: "in_progress" or "completed"` - The canonical name of the agent that produced this item. + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `ToolSearchCall object { id, arguments, call_id, 5 more }` + - `"in_progress"` - - `id: string` + - `"completed"` - The unique ID of the tool search call item. + - `type: "apply_patch_call"` - - `arguments: unknown` + The type of the item. Always `apply_patch_call`. - Arguments used for the tool search call. + - `"apply_patch_call"` - - `call_id: string` + - `id: optional string` - The unique ID of the tool search call generated by the model. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `execution: "server" or "client"` + - `agent: optional object { agent_name }` - Whether tool search was 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. - - `status: "in_progress" or "completed" or "incomplete"` + - `caller: optional object { type } or object { caller_id, type }` - The status of the tool search call item that was recorded. + The execution context that produced this tool call. - - `"in_progress"` + - `Direct object { type }` - - `"completed"` + - `type: "direct"` - - `"incomplete"` + The caller type. Always `direct`. - - `type: "tool_search_call"` + - `"direct"` - The type of the item. Always `tool_search_call`. + - `Program object { caller_id, type }` - - `"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"` - - `created_by: optional string` + - `ApplyPatchCallOutput object { call_id, status, type, 4 more }` - The identifier of the actor that created the item. + The streamed output emitted by an apply patch tool call. - - `ToolSearchOutput object { id, call_id, execution, 5 more }` + - `call_id: string` - - `id: string` + The unique ID of the apply patch tool call generated by the model. - The unique ID of the tool search output item. + - `status: "completed" or "failed"` - - `call_id: string` + The status of the apply patch tool call output. One of `completed` or `failed`. - The unique ID of the tool search call generated by the model. + - `"completed"` - - `execution: "server" or "client"` + - `"failed"` - Whether tool search was executed by the server or by the client. + - `type: "apply_patch_call_output"` - - `"server"` + The type of the item. Always `apply_patch_call_output`. - - `"client"` + - `"apply_patch_call_output"` - - `status: "in_progress" or "completed" or "incomplete"` + - `id: optional string` - The status of the tool search output item that was recorded. + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `"in_progress"` + - `agent: optional object { agent_name }` - - `"completed"` + The agent that produced this item. - - `"incomplete"` + - `agent_name: 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 canonical name of the agent that produced this item. - The loaded tool definitions returned by tool search. + - `caller: optional object { type } or object { caller_id, type }` - - `Function object { name, parameters, strict, 5 more }` + The execution context that produced this 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). + - `Direct object { type }` - - `name: string` + - `type: "direct"` - The name of the function to call. + The caller type. Always `direct`. - - `parameters: map[unknown]` + - `"direct"` - A JSON schema object describing the parameters of the function. + - `Program object { caller_id, type }` - - `strict: boolean` + - `caller_id: string` - Whether strict parameter validation is enforced for this function tool. + The call ID of the program item that produced this tool call. - - `type: "function"` + - `type: "program"` - The type of the function tool. Always `function`. + The caller type. Always `program`. - - `"function"` + - `"program"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `output: optional string` - The tool invocation context(s). + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - - `"direct"` + - `McpListTools object { id, server_label, tools, 3 more }` - - `"programmatic"` + A list of tools available on an MCP server. - - `defer_loading: optional boolean` + - `id: string` - Whether this function is deferred and loaded via tool search. + The unique ID of the list. - - `description: optional string` + - `server_label: string` - A description of the function. Used by the model to determine whether or not to call the function. + The label of the MCP server. - - `output_schema: optional map[unknown]` + - `tools: array of object { input_schema, name, annotations, description }` - A JSON schema object describing the JSON value encoded in string outputs for this function. + The tools available on the server. - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + - `input_schema: unknown` - 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 JSON schema describing the tool's input. - - `type: "file_search"` + - `name: string` - The type of the file search tool. Always `file_search`. + The name of the tool. - - `"file_search"` + - `annotations: optional unknown` - - `vector_store_ids: array of string` + Additional annotations about the tool. - The IDs of the vector stores to search. + - `description: optional string` - - `filters: optional object { key, type, value } or object { filters, type }` + The description of the tool. - A filter to apply. + - `type: "mcp_list_tools"` - - `ComparisonFilter object { key, type, value }` + The type of the item. Always `mcp_list_tools`. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `"mcp_list_tools"` - - `key: string` + - `agent: optional object { agent_name }` - The key to compare against the value. + The agent that produced this item. - - `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 + - `error: optional string` - - `"eq"` + Error message if the server could not list tools. - - `"ne"` + - `McpApprovalRequest object { id, arguments, name, 3 more }` - - `"gt"` + A request for human approval of a tool invocation. - - `"gte"` + - `id: string` - - `"lt"` + The unique ID of the approval request. - - `"lte"` + - `arguments: string` - - `"in"` + A JSON string of arguments for the tool. - - `"nin"` + - `name: string` - - `value: string or number or boolean or array of string or number` + The name of the tool to run. - The value to compare against the attribute key; supports string, number, or boolean types. + - `server_label: string` - - `string` + The label of the MCP server making the request. - - `number` + - `type: "mcp_approval_request"` - - `boolean` + The type of the item. Always `mcp_approval_request`. - - `array of string or number` + - `"mcp_approval_request"` - - `string` + - `agent: optional object { agent_name }` - - `number` + The agent that produced this item. - - `CompoundFilter object { filters, type }` + - `agent_name: string` - Combine multiple filters using `and` or `or`. + The canonical name of the agent that produced this item. - - `filters: array of object { key, type, value } or unknown` + - `McpApprovalResponse object { approval_request_id, approve, type, 3 more }` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + A response to an MCP approval request. - - `ComparisonFilter object { key, type, value }` + - `approval_request_id: string` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The ID of the approval request being answered. - - `key: string` + - `approve: boolean` - The key to compare against the value. + Whether the request was approved. - - `type: "eq" or "ne" or "gt" or 5 more` + - `type: "mcp_approval_response"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The type of the item. Always `mcp_approval_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 + - `"mcp_approval_response"` - - `"eq"` + - `id: optional string` - - `"ne"` + The unique ID of the approval response - - `"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"` + - `reason: optional string` - - `"nin"` + Optional reason for the decision. - - `value: string or number or boolean or array of string or number` + - `McpCall object { id, arguments, name, 7 more }` - The value to compare against the attribute key; supports string, number, or boolean types. + An invocation of a tool on an MCP server. - - `string` + - `id: string` - - `number` + The unique ID of the tool call. - - `boolean` + - `arguments: string` - - `array of string or number` + A JSON string of the arguments passed to the tool. - - `string` + - `name: string` - - `number` + The name of the tool that was run. - - `unknown` + - `server_label: string` - - `type: "and" or "or"` + The label of the MCP server running the tool. - Type of operation: `and` or `or`. + - `type: "mcp_call"` - - `"and"` + The type of the item. Always `mcp_call`. - - `"or"` + - `"mcp_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 }` + - `approval_request_id: optional string` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + 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. - - `embedding_weight: number` + - `error: optional string` - The weight of the embedding in the reciprocal ranking fusion. + The error from the tool call, if any. - - `text_weight: number` + - `output: optional string` - The weight of the text in the reciprocal ranking fusion. + The output from the tool call. - - `ranker: optional "auto" or "default-2024-11-15"` + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - The ranker to use for the file search. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `"auto"` + - `"in_progress"` - - `"default-2024-11-15"` + - `"completed"` - - `score_threshold: optional number` + - `"incomplete"` - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + - `"calling"` - - `Computer object { type }` + - `"failed"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `CustomToolCallOutput object { call_id, output, type, 3 more }` - - `type: "computer"` + The output of a custom tool call from your code, being sent back to the model. - The type of the computer tool. Always `computer`. + - `call_id: string` - - `"computer"` + The call ID, used to map this custom tool call output to a custom tool call. - - `ComputerUsePreview object { display_height, display_width, environment, type }` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `display_height: number` + - `StringOutput = string` - The height of the computer display. + A string of the output of the custom tool call. - - `display_width: number` + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - The width of the computer display. + Text, image, or file output of the custom tool call. - - `environment: "windows" or "mac" or "linux" or 2 more` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - The type of computer environment to control. + A text input to the model. - - `"windows"` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `"mac"` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `"linux"` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `"ubuntu"` + A file input to the model. - - `"browser"` + - `type: "custom_tool_call_output"` - - `type: "computer_use_preview"` + The type of the custom tool call output. Always `custom_tool_call_output`. - The type of the computer use tool. Always `computer_use_preview`. + - `"custom_tool_call_output"` - - `"computer_use_preview"` + - `id: optional string` - - `WebSearch object { type, filters, search_context_size, user_location }` + The unique ID of the custom tool call output in the OpenAI platform. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/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"` + - `caller: optional object { type } or object { caller_id, type }` - - `filters: optional object { allowed_domains }` + The execution context that produced this tool call. - Filters for the search. + - `Direct object { type }` - - `allowed_domains: optional array of string` + - `type: "direct"` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + The caller type. Always `direct`. - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `"direct"` - - `search_context_size: optional "low" or "medium" or "high"` + - `Program 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. + - `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`. - - `user_location: optional object { city, country, region, 2 more }` + - `"program"` - The approximate location of the user. + - `CustomToolCall object { call_id, input, name, 5 more }` - - `city: optional string` + A call to a custom tool created by the model. - Free text input for the city of the user, e.g. `San Francisco`. + - `call_id: string` - - `country: optional string` + An identifier used to map this custom tool call to a tool call output. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `input: string` - - `region: optional string` + The input for the custom tool call generated by the model. - Free text input for the region of the user, e.g. `California`. + - `name: string` - - `timezone: optional string` + The name of the custom tool being called. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `type: "custom_tool_call"` - - `type: optional "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` - - `Mcp object { server_label, type, allowed_callers, 9 more }` + The unique ID of the custom tool call in the OpenAI platform. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/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 }` + - `namespace: optional string` - A filter object to specify which tools are allowed. + The namespace of the custom tool being called. - - `read_only: optional boolean` + - `CompactionTrigger object { type, agent }` - 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. + Compacts the current context. Must be the final input item. - - `tool_names: optional array of string` + - `type: "compaction_trigger"` - List of allowed tool names. + The type of the item. Always `compaction_trigger`. - - `authorization: optional string` + - `"compaction_trigger"` - 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](https://platform.openai.com/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` + - `ItemReference object { id, agent, type }` - - `"connector_dropbox"` + An internal identifier for an item to reference. - - `"connector_gmail"` + - `id: string` - - `"connector_googlecalendar"` + The ID of the item to reference. - - `"connector_googledrive"` + - `agent: optional object { agent_name }` - - `"connector_microsoftteams"` + The agent that produced this item. - - `"connector_outlookcalendar"` + - `agent_name: string` - - `"connector_outlookemail"` + The canonical name of the agent that produced this item. - - `"connector_sharepoint"` + - `type: optional "item_reference"` - - `defer_loading: optional boolean` + The type of item to reference. Always `item_reference`. - Whether this MCP tool is deferred and discovered via tool search. + - `"item_reference"` - - `headers: optional map[string]` + - `Program object { id, call_id, code, 3 more }` - 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 unique ID of this program item. - Specify which of the MCP server's tools require approval. + - `call_id: string` - - `McpToolApprovalFilter object { always, never }` + The stable call ID of the program 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. + - `code: string` - - `always: optional object { read_only, tool_names }` + The JavaScript source executed by programmatic tool calling. - A filter object to specify which tools are allowed. + - `fingerprint: string` - - `read_only: optional boolean` + Opaque program replay fingerprint that must be round-tripped. - 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` + The item type. Always `program`. - List of allowed tool names. + - `"program"` - - `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` + - `ProgramOutput object { id, call_id, result, 3 more }` - List of allowed tool names. + - `id: string` - - `McpToolApprovalSetting = "always" or "never"` + The unique ID of this program output 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. + - `call_id: string` - - `"always"` + The call ID of the program item. - - `"never"` + - `result: string` - - `server_description: optional string` + The result produced by the program item. - Optional description of the MCP server, used to provide more context. + - `status: "completed" or "incomplete"` - - `server_url: optional string` + The terminal status of the program output. - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `"completed"` - - `tunnel_id: optional string` + - `"incomplete"` - 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_output"` - - `CodeInterpreter object { container, type, allowed_callers }` + The item type. Always `program_output`. - A tool that runs Python code to help generate a response to a prompt. + - `"program_output"` - - `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 }` + - `response_id: string` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + The ID of the active response that should receive the input. - - `type: "auto"` + - `type: "response.inject"` - Always `auto`. + The event discriminator. Always `response.inject`. - - `"auto"` + - `"response.inject"` - - `file_ids: optional array of string` +### Beta Response Inject Failed Event - An optional list of uploaded files to make available to your code. +- `BetaResponseInjectFailedEvent object { error, input, response_id, 3 more }` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + 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 memory limit for the code interpreter container. + - `error: object { code, message }` - - `"1g"` + Information about why the input was not committed. - - `"4g"` + - `code: "response_already_completed" or "response_not_found"` - - `"16g"` + A machine-readable error code. - - `"64g"` + - `"response_already_completed"` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `"response_not_found"` - Network access policy for the container. + - `message: string` - - `BetaContainerNetworkPolicyDisabled object { type }` + A human-readable description of the error. - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `input: array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` - - `type: "code_interpreter"` + The raw input items that were not committed. - The type of the code interpreter tool. Always `code_interpreter`. + - `BetaEasyInputMessage object { content, role, phase, type }` - - `"code_interpreter"` + 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. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `content: string or BetaResponseInputMessageContentList` - The tool invocation context(s). + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `"direct"` + - `TextInput = string` - - `"programmatic"` + A text input to the model. - - `ProgrammaticToolCalling object { type }` + - `BetaResponseInputMessageContentList = array of BetaResponseInputContent` - - `type: "programmatic_tool_calling"` + A list of one or many input items to the model, containing different content + types. - The type of the tool. Always `programmatic_tool_calling`. + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `"programmatic_tool_calling"` + A text input to the model. - - `ImageGeneration object { type, action, background, 9 more }` + - `text: string` - A tool that generates images using the GPT image models. + The text input to the model. - - `type: "image_generation"` + - `type: "input_text"` - The type of the image generation tool. Always `image_generation`. + The type of the input item. Always `input_text`. - - `"image_generation"` + - `"input_text"` - - `action: optional "generate" or "edit" or "auto"` + - `prompt_cache_breakpoint: optional object { mode }` - Whether to generate a new image or edit an existing image. Default: `auto`. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `"generate"` + - `mode: "explicit"` - - `"edit"` + The breakpoint mode. Always `explicit`. - - `"auto"` + - `"explicit"` - - `background: optional "transparent" or "opaque" or "auto"` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + - `detail: "low" or "high" or "auto" or "original"` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `"transparent"` + - `"low"` - - `"opaque"` + - `"high"` - `"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"` + - `"original"` - - `"low"` + - `type: "input_image"` - - `input_image_mask: optional object { file_id, image_url }` + The type of the input item. Always `input_image`. - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `"input_image"` - `file_id: optional string` - File ID for the mask image. + The ID of the file to be sent to the model. - `image_url: optional string` - Base64-encoded mask image. - - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - The image generation model to use. Default: `gpt-image-1`. + - `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. - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `mode: "explicit"` - The image generation model to use. Default: `gpt-image-1`. + The breakpoint mode. Always `explicit`. - - `"gpt-image-1"` + - `"explicit"` - - `"gpt-image-1-mini"` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `"gpt-image-2"` + A file input to the model. - - `"gpt-image-2-2026-04-21"` + - `type: "input_file"` - - `"gpt-image-1.5"` + The type of the input item. Always `input_file`. - - `"chatgpt-image-latest"` + - `"input_file"` - - `moderation: optional "auto" or "low"` + - `detail: optional "auto" or "low" or "high"` - Moderation level for the generated image. Default: `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`. - `"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"` + - `"high"` - - `partial_images: optional number` + - `file_data: optional string` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + The content of the file to be sent to the model. - - `quality: optional "low" or "medium" or "high" or "auto"` + - `file_id: optional string` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + The ID of the file to be sent to the model. - - `"low"` + - `file_url: optional string` - - `"medium"` + The URL of the file to be sent to the model. - - `"high"` + - `filename: optional string` - - `"auto"` + The name of the file to be sent to the model. - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `prompt_cache_breakpoint: optional object { mode }` - 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`. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `string` + - `mode: "explicit"` - - `"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"` - - `"1024x1024"` + - `role: "user" or "assistant" or "system" or "developer"` - - `"1024x1536"` + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - - `"1536x1024"` + - `"user"` - - `"auto"` + - `"assistant"` - - `LocalShell object { type }` + - `"system"` - A tool that allows the model to execute shell commands in a local environment. + - `"developer"` - - `type: "local_shell"` + - `phase: optional "commentary" or "final_answer"` - The type of the local shell tool. Always `local_shell`. + 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. - - `"local_shell"` + - `"commentary"` - - `Shell object { type, allowed_callers, environment }` + - `"final_answer"` - A tool that allows the model to execute shell commands. + - `type: optional "message"` - - `type: "shell"` + The type of the message input. Always `message`. - The type of the shell tool. Always `shell`. + - `"message"` - - `"shell"` + - `Message object { content, role, agent, 2 more }` - - `allowed_callers: optional array of "direct" or "programmatic"` + 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 tool invocation context(s). + - `content: BetaResponseInputMessageContentList` - - `"direct"` + A list of one or many input items to the model, containing different content + types. - - `"programmatic"` + - `role: "user" or "system" or "developer"` - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + The role of the message input. One of `user`, `system`, or `developer`. - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `"user"` - - `BetaLocalEnvironment object { type, skills }` + - `"system"` - - `BetaContainerReference object { container_id, type }` + - `"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](https://platform.openai.com/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"` - - `Namespace object { description, name, tools, type }` + - `URLCitation object { end_index, start_index, title, 2 more }` - Groups function/custom tools under a shared namespace. + A citation for a web resource used to generate a model response. - - `description: string` + - `end_index: number` - A description of the namespace shown to the model. + The index of the last character of the URL citation in the message. - - `name: string` + - `start_index: number` - The namespace name used in tool calls (for example, `crm`). + The index of the first character of the URL citation in the message. - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + - `title: string` - The function/custom tools available inside this namespace. + The title of the web resource. - - `Function object { name, type, allowed_callers, 5 more }` + - `type: "url_citation"` - - `name: string` + The type of the URL citation. Always `url_citation`. - - `type: "function"` + - `"url_citation"` - - `"function"` + - `url: string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The URL of the web resource. - The tool invocation context(s). + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - - `"direct"` + A citation for a container file used to generate a model response. - - `"programmatic"` + - `container_id: string` - - `defer_loading: optional boolean` + The ID of the container file. - Whether this function should be deferred and discovered via tool search. + - `end_index: number` - - `description: optional string` + The index of the last character of the container file citation in the message. - - `output_schema: optional map[unknown]` + - `file_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 file. - - `parameters: optional unknown` + - `filename: string` - - `strict: optional boolean` + The filename of the container file cited. - 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. + - `start_index: number` - - `Custom object { name, type, allowed_callers, 3 more }` + The index of the first character of the container file citation in the message. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `type: "container_file_citation"` - - `name: string` + The type of the container file citation. Always `container_file_citation`. - The name of the custom tool, used to identify it in tool calls. + - `"container_file_citation"` - - `type: "custom"` + - `FilePath object { file_id, index, type }` - The type of the custom tool. Always `custom`. + A path to a file. - - `"custom"` + - `file_id: string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The ID of the file. - The tool invocation context(s). + - `index: number` - - `"direct"` + The index of the file in the list of files. - - `"programmatic"` + - `type: "file_path"` - - `defer_loading: optional boolean` + The type of the file path. Always `file_path`. - Whether this tool should be deferred and discovered via tool search. + - `"file_path"` - - `description: optional string` + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - Optional description of the custom tool, used to provide more context. + - `token: string` - - `format: optional object { type } or object { definition, syntax, type }` + - `bytes: array of number` - The input format for the custom tool. Default is unconstrained text. + - `logprob: number` - - `Text object { type }` + - `top_logprobs: array of object { token, bytes, logprob }` - Unconstrained free-form text. + - `token: string` - - `type: "text"` + - `bytes: array of number` - Unconstrained text format. Always `text`. + - `logprob: number` - - `"text"` + - `text: string` - - `Grammar object { definition, syntax, type }` + The text output from the model. - A grammar defined by the user. + - `type: "output_text"` - - `definition: string` + The type of the output text. Always `output_text`. - The grammar definition. + - `"output_text"` - - `syntax: "lark" or "regex"` + - `BetaResponseOutputRefusal object { refusal, type }` - The syntax of the grammar definition. One of `lark` or `regex`. + A refusal from the model. - - `"lark"` + - `refusal: string` - - `"regex"` + The refusal explanation from the model. - - `type: "grammar"` + - `type: "refusal"` - Grammar format. Always `grammar`. + The type of the refusal. Always `refusal`. - - `"grammar"` + - `"refusal"` - - `type: "namespace"` + - `role: "assistant"` - The type of the tool. Always `namespace`. + The role of the output message. Always `assistant`. - - `"namespace"` + - `"assistant"` - - `ToolSearch object { type, description, execution, parameters }` + - `status: "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` + - `type: "message"` - Description shown to the model for a client-executed tool search tool. + The type of the output message. Always `message`. - - `execution: optional "server" or "client"` + - `"message"` - Whether tool search is executed by the server or by the client. + - `agent: optional object { agent_name }` - - `"server"` + The agent that produced this item. - - `"client"` + - `agent_name: string` - - `parameters: optional unknown` + The canonical name of the agent that produced this item. - Parameter schema for a client-executed tool search tool. + - `phase: optional "commentary" or "final_answer"` - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + 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. - 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). + - `"commentary"` - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `"final_answer"` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `FileSearchCall object { id, queries, status, 3 more }` - - `"web_search_preview"` + The results of a file search tool call. See the + [file search guide](/docs/guides/tools-file-search) for more information. - - `"web_search_preview_2025_03_11"` + - `id: string` - - `search_content_types: optional array of "text" or "image"` + The unique ID of the file search tool call. - - `"text"` + - `queries: array of string` - - `"image"` + The queries used to search for files. - - `search_context_size: optional "low" or "medium" or "high"` + - `status: "in_progress" or "searching" or "completed" or 2 more` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `"low"` + - `"in_progress"` - - `"medium"` + - `"searching"` - - `"high"` + - `"completed"` - - `user_location: optional object { type, city, country, 2 more }` + - `"incomplete"` - The user's location. + - `"failed"` - - `type: "approximate"` + - `type: "file_search_call"` - The type of location approximation. Always `approximate`. + The type of the file search tool call. Always `file_search_call`. - - `"approximate"` + - `"file_search_call"` - - `city: optional string` + - `agent: optional object { agent_name }` - Free text input for the city of the user, e.g. `San Francisco`. + The agent that produced this item. - - `country: optional string` + - `agent_name: string` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The canonical name of the agent that produced this item. - - `region: optional string` + - `results: optional array of object { attributes, file_id, filename, 2 more }` - Free text input for the region of the user, e.g. `California`. + The results of the file search tool call. - - `timezone: optional string` + - `attributes: optional map[string or number or boolean]` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + 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. - - `ApplyPatch object { type, allowed_callers }` + - `string` - Allows the assistant to create, delete, or update files using unified diffs. + - `number` - - `type: "apply_patch"` + - `boolean` - The type of the tool. Always `apply_patch`. + - `file_id: optional string` - - `"apply_patch"` + The unique ID of the file. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `filename: optional string` - The tool invocation context(s). + The name of the file. - - `"direct"` + - `score: optional number` - - `"programmatic"` + The relevance score of the file - a value between 0 and 1. - - `type: "tool_search_output"` + - `text: optional string` - The type of the item. Always `tool_search_output`. + The text that was retrieved from the file. - - `"tool_search_output"` + - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` - - `agent: optional object { agent_name }` + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - The agent that produced this item. + - `id: string` - - `agent_name: string` + The unique ID of the computer call. - The canonical name of the agent that produced this item. + - `call_id: string` - - `created_by: optional string` + An identifier used when responding to the tool call with output. - The identifier of the actor that created the item. + - `pending_safety_checks: array of object { id, code, message }` - - `AdditionalTools object { id, role, tools, 2 more }` + The pending safety checks for the computer call. - `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. + The ID of the pending safety check. - - `"unknown"` + - `code: optional string` - - `"user"` + The type of the pending safety check. - - `"assistant"` + - `message: optional string` - - `"system"` + Details about the pending safety check. - - `"critic"` + - `status: "in_progress" or "completed" or "incomplete"` - - `"discriminator"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"developer"` + - `"in_progress"` - - `"tool"` + - `"completed"` - - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` + - `"incomplete"` - The additional tool definitions made available at this item. + - `type: "computer_call"` - - `Function object { name, parameters, strict, 5 more }` + The type of the computer call. Always `computer_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). + - `"computer_call"` - - `name: string` + - `action: optional BetaComputerAction` - The name of the function to call. + A click action. - - `parameters: map[unknown]` + - `Click object { button, type, x, 2 more }` - A JSON schema object describing the parameters of the function. + A click action. - - `strict: boolean` + - `button: "left" or "right" or "wheel" or 2 more` - Whether strict parameter validation is enforced for this function tool. + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `type: "function"` + - `"left"` - The type of the function tool. Always `function`. + - `"right"` - - `"function"` + - `"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`. - - `defer_loading: optional boolean` + - `"click"` - Whether this function is deferred and loaded via tool search. + - `x: number` - - `description: optional string` + The x-coordinate where the click occurred. - A description of the function. Used by the model to determine whether or not to call the function. + - `y: number` - - `output_schema: optional map[unknown]` + The y-coordinate where the click occurred. - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `keys: optional array of string` - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + The keys being held while clicking. - 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). + - `DoubleClick object { keys, type, x, y }` - - `type: "file_search"` + A double click action. - The type of the file search tool. Always `file_search`. + - `keys: array of string` - - `"file_search"` + The keys being held while double-clicking. - - `vector_store_ids: array of string` + - `type: "double_click"` - The IDs of the vector stores to search. + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `filters: optional object { key, type, value } or object { filters, type }` + - `"double_click"` - A filter to apply. + - `x: number` - - `ComparisonFilter object { key, type, value }` + The x-coordinate where the double click occurred. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `y: number` - - `key: string` + The y-coordinate where the double click occurred. - The key to compare against the value. + - `Drag object { path, type, keys }` - - `type: "eq" or "ne" or "gt" or 5 more` + A drag action. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `path: array of object { x, y }` - - `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 array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `"eq"` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `"ne"` + - `x: number` - - `"gt"` + The x-coordinate. - - `"gte"` + - `y: number` - - `"lt"` + The y-coordinate. - - `"lte"` + - `type: "drag"` - - `"in"` + Specifies the event type. For a drag action, this property is always set to `drag`. - - `"nin"` + - `"drag"` - - `value: string or number or boolean or array of string or number` + - `keys: optional array of string` - The value to compare against the attribute key; supports string, number, or boolean types. + The keys being held while dragging the mouse. - - `string` + - `Keypress object { keys, type }` - - `number` + A collection of keypresses the model would like to perform. - - `boolean` + - `keys: array of string` - - `array of string or number` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `string` + - `type: "keypress"` - - `number` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `CompoundFilter object { filters, type }` + - `"keypress"` - Combine multiple filters using `and` or `or`. + - `Move object { type, x, y, keys }` - - `filters: array of object { key, type, value } or unknown` + A mouse move action. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `type: "move"` - - `ComparisonFilter object { key, type, value }` + Specifies the event type. For a move action, this property is always set to `move`. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `"move"` - - `key: string` + - `x: number` - The key to compare against the value. + The x-coordinate to move to. - - `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 to move to. - - `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: optional array of string` - - `"eq"` + The keys being held while moving the mouse. - - `"ne"` + - `Screenshot object { type }` - - `"gt"` + A screenshot action. - - `"gte"` + - `type: "screenshot"` - - `"lt"` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `"lte"` + - `"screenshot"` - - `"in"` + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - - `"nin"` + A scroll action. - - `value: string or number or boolean or array of string or number` + - `scroll_x: number` - The value to compare against the attribute key; supports string, number, or boolean types. + The horizontal scroll distance. - - `string` + - `scroll_y: number` - - `number` + The vertical scroll distance. - - `boolean` + - `type: "scroll"` - - `array of string or number` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `string` + - `"scroll"` - - `number` + - `x: number` - - `unknown` + The x-coordinate where the scroll occurred. - - `type: "and" or "or"` + - `y: number` - Type of operation: `and` or `or`. + The y-coordinate where the scroll occurred. - - `"and"` + - `keys: optional array of string` - - `"or"` + The keys being held while scrolling. - - `max_num_results: optional number` + - `Type object { text, type }` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + An action to type in text. - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `text: string` - Ranking options for search. + The text to type. - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `type: "type"` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + Specifies the event type. For a type action, this property is always set to `type`. - - `embedding_weight: number` + - `"type"` - The weight of the embedding in the reciprocal ranking fusion. + - `Wait object { type }` - - `text_weight: number` + A wait action. - The weight of the text in the reciprocal ranking fusion. + - `type: "wait"` - - `ranker: optional "auto" or "default-2024-11-15"` + Specifies the event type. For a wait action, this property is always set to `wait`. - The ranker to use for the file search. + - `"wait"` - - `"auto"` + - `actions: optional BetaComputerActionList` - - `"default-2024-11-15"` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `score_threshold: optional number` + - `Click object { button, type, x, 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. + A click action. - - `Computer object { type }` + - `DoubleClick object { keys, type, x, y }` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + A double click action. - - `type: "computer"` + - `Drag object { path, type, keys }` - The type of the computer tool. Always `computer`. + A drag action. - - `"computer"` + - `Keypress object { keys, type }` - - `ComputerUsePreview object { display_height, display_width, environment, type }` + A collection of keypresses the model would like to perform. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `Move object { type, x, y, keys }` - - `display_height: number` + A mouse move action. - The height of the computer display. + - `Screenshot object { type }` - - `display_width: number` + A screenshot action. - 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. + - `Type object { text, type }` - - `"windows"` + An action to type in text. - - `"mac"` + - `Wait object { type }` - - `"linux"` + A wait action. - - `"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"` + - `ComputerCallOutput object { call_id, output, type, 4 more }` - - `WebSearch object { type, filters, search_context_size, user_location }` + The output of a computer tool call. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `call_id: string` - - `type: "web_search" or "web_search_2025_08_26"` + The ID of the computer tool call that produced the output. - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `output: BetaResponseComputerToolCallOutputScreenshot` - - `"web_search"` + A computer screenshot image used with the computer use tool. - - `"web_search_2025_08_26"` + - `type: "computer_screenshot"` - - `filters: optional object { allowed_domains }` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - Filters for the search. + - `"computer_screenshot"` - - `allowed_domains: optional array of string` + - `file_id: optional string` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + The identifier of an uploaded file that contains the screenshot. - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `image_url: optional string` - - `search_context_size: optional "low" or "medium" or "high"` + The URL of the screenshot image. - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `type: "computer_call_output"` - - `"low"` + The type of the computer tool call output. Always `computer_call_output`. - - `"medium"` + - `"computer_call_output"` - - `"high"` + - `id: optional string` - - `user_location: optional object { city, country, region, 2 more }` + The ID of the computer tool call output. - The approximate location of the user. + - `acknowledged_safety_checks: optional array of object { id, code, message }` - - `city: optional string` + The safety checks reported by the API that have been acknowledged by the developer. - Free text input for the city of the user, e.g. `San Francisco`. + - `id: string` - - `country: optional string` + The ID of the pending safety check. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `code: optional string` - - `region: optional string` + The type of the pending safety check. - Free text input for the region of the user, e.g. `California`. + - `message: optional string` - - `timezone: optional string` + Details about the pending safety check. - 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 }` + - `status: optional "in_progress" or "completed" or "incomplete"` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - - `server_label: string` + - `"in_progress"` - A label for this MCP server, used to identify it in tool calls. + - `"completed"` - - `type: "mcp"` + - `"incomplete"` - The type of the MCP tool. Always `mcp`. + - `WebSearchCall object { id, action, status, 2 more }` - - `"mcp"` + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `id: string` - The tool invocation context(s). + The unique ID of the web search tool call. - - `"direct"` + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - - `"programmatic"` + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). - - `allowed_tools: optional array of string or object { read_only, tool_names }` + - `Search object { type, queries, query, sources }` - List of allowed tool names or a filter object. + Action type "search" - Performs a web search query. - - `McpAllowedTools = array of string` + - `type: "search"` - A string array of allowed tool names + The action type. - - `McpToolFilter object { read_only, tool_names }` + - `"search"` - A filter object to specify which tools are allowed. + - `queries: optional array of string` - - `read_only: optional boolean` + The search queries. - 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. + - `query: optional string` - - `tool_names: optional array of string` + The search query. - List of allowed tool names. + - `sources: optional array of object { type, url }` - - `authorization: optional string` + The sources used in the search. - 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: "url"` - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + The type of source. Always `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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + - `"url"` - Currently supported `connector_id` values are: + - `url: string` - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + The URL of the source. - - `"connector_dropbox"` + - `OpenPage object { type, url }` - - `"connector_gmail"` + Action type "open_page" - Opens a specific URL from search results. - - `"connector_googlecalendar"` + - `type: "open_page"` - - `"connector_googledrive"` + The action type. - - `"connector_microsoftteams"` + - `"open_page"` - - `"connector_outlookcalendar"` + - `url: optional string` - - `"connector_outlookemail"` + The URL opened by the model. - - `"connector_sharepoint"` + - `FindInPage object { pattern, type, url }` - - `defer_loading: optional boolean` + Action type "find_in_page": Searches for a pattern within a loaded page. - Whether this MCP tool is deferred and discovered via tool search. + - `pattern: string` - - `headers: optional map[string]` + The pattern or text to search for within the page. - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `type: "find_in_page"` - - `require_approval: optional object { always, never } or "always" or "never"` + The action type. - Specify which of the MCP server's tools require approval. + - `"find_in_page"` - - `McpToolApprovalFilter object { always, never }` + - `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. + The URL of the page searched for the pattern. - - `always: optional object { read_only, tool_names }` + - `status: "in_progress" or "searching" or "completed" or "failed"` - A filter object to specify which tools are allowed. + The status of the web search tool call. - - `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. + - `"searching"` - - `tool_names: optional array of string` + - `"completed"` - List of allowed tool names. + - `"failed"` - - `never: optional object { read_only, tool_names }` + - `type: "web_search_call"` - A filter object to specify which tools are allowed. + The type of the web search tool call. Always `web_search_call`. - - `read_only: optional boolean` + - `"web_search_call"` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `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. + - `FunctionCall object { arguments, call_id, name, 6 more }` - - `"always"` + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. - - `"never"` + - `arguments: string` - - `server_description: optional string` + A JSON string of the arguments to pass to the function. - 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. + - `name: string` - - `tunnel_id: optional string` + The name of the function to run. - 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: "function_call"` - - `CodeInterpreter object { container, type, allowed_callers }` + The type of the function tool call. Always `function_call`. - A tool that runs Python code to help generate a response to a prompt. + - `"function_call"` - - `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 function tool call. - - `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. + - `"direct"` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `Program object { caller_id, type }` - The memory limit for the code interpreter container. + - `caller_id: string` - - `"1g"` + The call ID of the program item that produced this tool call. - - `"4g"` + - `type: "program"` - - `"16g"` + - `"program"` - - `"64g"` + - `namespace: optional string` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + The namespace of the function to run. - Network access policy for the container. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `BetaContainerNetworkPolicyDisabled object { type }` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `"in_progress"` - - `type: "code_interpreter"` + - `"completed"` - The type of the code interpreter tool. Always `code_interpreter`. + - `"incomplete"` - - `"code_interpreter"` + - `FunctionCallOutput object { call_id, output, type, 4 more }` - - `allowed_callers: optional array of "direct" or "programmatic"` + The output of a function tool call. - The tool invocation context(s). + - `call_id: string` - - `"direct"` + The unique ID of the function tool call generated by the model. - - `"programmatic"` + - `output: string or array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` - - `ProgrammaticToolCalling object { type }` + Text, image, or file output of the function tool call. - - `type: "programmatic_tool_calling"` + - `string` - The type of the tool. Always `programmatic_tool_calling`. + A JSON string of the output of the function tool call. - - `"programmatic_tool_calling"` + - `array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` - - `ImageGeneration object { type, action, background, 9 more }` + An array of content outputs (text, image, file) for the function tool call. - A tool that generates images using the GPT image models. + - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` - - `type: "image_generation"` + A text input to the model. - The type of the image generation tool. Always `image_generation`. + - `text: string` - - `"image_generation"` + The text input to the model. - - `action: optional "generate" or "edit" or "auto"` + - `type: "input_text"` - Whether to generate a new image or edit an existing image. Default: `auto`. + The type of the input item. Always `input_text`. - - `"generate"` + - `"input_text"` - - `"edit"` + - `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. - - `background: optional "transparent" or "opaque" or "auto"` + - `mode: "explicit"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + The breakpoint mode. Always `explicit`. - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + - `"explicit"` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` - - `"transparent"` + An image input to the model. Learn about [image inputs](/docs/guides/vision) - - `"opaque"` + - `type: "input_image"` - - `"auto"` + The type of the input item. Always `input_image`. - - `input_fidelity: optional "high" or "low"` + - `"input_image"` - 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`. + - `detail: optional "low" or "high" or "auto" or "original"` - - `"high"` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - `"low"` - - `input_image_mask: optional object { file_id, image_url }` + - `"high"` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `"auto"` + + - `"original"` - `file_id: optional string` - File ID for the mask image. + The ID of the file to be sent to the model. - `image_url: optional string` - Base64-encoded mask image. - - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - The image generation model to use. Default: `gpt-image-1`. + - `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. - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `mode: "explicit"` - The image generation model to use. Default: `gpt-image-1`. + The breakpoint mode. Always `explicit`. - - `"gpt-image-1"` + - `"explicit"` - - `"gpt-image-1-mini"` + - `BetaResponseInputFileContent object { type, detail, file_data, 4 more }` - - `"gpt-image-2"` + A file input to the model. - - `"gpt-image-2-2026-04-21"` + - `type: "input_file"` - - `"gpt-image-1.5"` + The type of the input item. Always `input_file`. - - `"chatgpt-image-latest"` + - `"input_file"` - - `moderation: optional "auto" or "low"` + - `detail: optional "auto" or "low" or "high"` - Moderation level for the generated image. Default: `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`. - `"auto"` - `"low"` - - `output_compression: optional number` + - `"high"` - Compression level for the output image. Default: 100. + - `file_data: optional string` - - `output_format: optional "png" or "webp" or "jpeg"` + The base64-encoded data of the file to be sent to the model. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `file_id: optional string` - - `"png"` + The ID of the file to be sent to the model. - - `"webp"` + - `file_url: optional string` - - `"jpeg"` + The URL of the file to be sent to the model. - - `partial_images: optional number` + - `filename: optional string` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + The name of the file to be sent to the model. - - `quality: optional "low" or "medium" or "high" or "auto"` + - `prompt_cache_breakpoint: optional object { mode }` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `"low"` + - `mode: "explicit"` - - `"medium"` + The breakpoint mode. Always `explicit`. - - `"high"` + - `"explicit"` - - `"auto"` + - `type: "function_call_output"` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + The type of the function tool call output. Always `function_call_output`. - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `"function_call_output"` - - `string` + - `id: optional string` - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + The unique ID of the function 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 }` - - `"1024x1024"` + The agent that produced this item. - - `"1024x1536"` + - `agent_name: string` - - `"1536x1024"` + The canonical name of the agent that produced this item. - - `"auto"` + - `caller: optional object { type } or object { caller_id, type }` - - `LocalShell object { type }` + The execution context that produced this tool call. - A tool that allows the model to execute shell commands in a local environment. + - `Direct object { type }` - - `type: "local_shell"` + - `type: "direct"` - The type of the local shell tool. Always `local_shell`. + The caller type. Always `direct`. - - `"local_shell"` + - `"direct"` - - `Shell object { type, allowed_callers, environment }` + - `Program object { caller_id, type }` - A tool that allows the model to execute shell commands. + - `caller_id: string` - - `type: "shell"` + The call ID of the program item that produced this tool call. - The type of the shell tool. Always `shell`. + - `type: "program"` - - `"shell"` + The caller type. Always `program`. - - `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"` - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + - `"completed"` - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `"incomplete"` - - `BetaLocalEnvironment object { type, skills }` + - `AgentMessage object { author, content, recipient, 3 more }` - - `BetaContainerReference object { container_id, type }` + A message routed between agents. - - `Custom object { name, type, allowed_callers, 3 more }` + - `author: string` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The sending agent identity. - - `name: string` + - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` - The name of the custom tool, used to identify it in tool calls. + Plaintext, image, or encrypted content sent between agents. - - `type: "custom"` + - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` - The type of the custom tool. Always `custom`. + A text input to the model. - - `"custom"` + - `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 tool should be deferred and discovered via tool search. + - `type: "encrypted_content"` - - `description: optional string` + The type of the input item. Always `encrypted_content`. - Optional description of the custom tool, used to provide more context. + - `"encrypted_content"` - - `format: optional object { type } or object { definition, syntax, type }` + - `recipient: string` - The input format for the custom tool. Default is unconstrained text. + The destination agent identity. - - `Text object { type }` + - `type: "agent_message"` - Unconstrained free-form text. + The item type. Always `agent_message`. - - `type: "text"` + - `"agent_message"` - Unconstrained text format. Always `text`. + - `id: optional string` - - `"text"` + The unique ID of this agent message item. - - `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"` + - `MultiAgentCall object { action, arguments, call_id, 3 more }` - The syntax of the grammar definition. One of `lark` or `regex`. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `"lark"` + The multi-agent action that was executed. - - `"regex"` + - `"spawn_agent"` - - `type: "grammar"` + - `"interrupt_agent"` - Grammar format. Always `grammar`. + - `"list_agents"` - - `"grammar"` + - `"send_message"` - - `Namespace object { description, name, tools, type }` + - `"followup_task"` - Groups function/custom tools under a shared namespace. + - `"wait_agent"` - - `description: string` + - `arguments: string` - A description of the namespace shown to the model. + The action arguments as a JSON string. - - `name: string` + - `call_id: string` - The namespace name used in tool calls (for example, `crm`). + The unique ID linking this call to its output. - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + - `type: "multi_agent_call"` - The function/custom tools available inside this namespace. + The item type. Always `multi_agent_call`. - - `Function object { name, type, allowed_callers, 5 more }` + - `"multi_agent_call"` - - `name: string` + - `id: optional string` - - `type: "function"` + The unique ID of this multi-agent call. - - `"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"` + - `MultiAgentCallOutput object { action, call_id, output, 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 produced this result. - - `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 }` + - `call_id: string` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The unique ID of the multi-agent call. - - `name: string` + - `output: array of object { text, type, annotations }` - The name of the custom tool, used to identify it in tool calls. + Text output returned by the multi-agent action. - - `type: "custom"` + - `text: string` - The type of the custom tool. Always `custom`. + The text content. - - `"custom"` + - `type: "output_text"` - - `allowed_callers: optional array of "direct" or "programmatic"` + The content type. Always `output_text`. - The tool invocation context(s). + - `"output_text"` - - `"direct"` + - `annotations: optional array of object { file_id, filename, index, type } or array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` - - `"programmatic"` + Citations associated with the text content. - - `defer_loading: optional boolean` + - `array of object { file_id, filename, index, type }` - Whether this tool should be deferred and discovered via tool search. + - `file_id: string` - - `description: optional string` + The ID of the file. - Optional description of the custom tool, used to provide more context. + - `filename: string` - - `format: optional object { type } or object { definition, syntax, type }` + The filename of the file cited. - The input format for the custom tool. Default is unconstrained text. + - `index: number` - - `Text object { type }` + The index of the file in the list of files. - Unconstrained free-form text. + - `type: "file_citation"` - - `type: "text"` + The citation type. Always `file_citation`. - Unconstrained text format. Always `text`. + - `"file_citation"` - - `"text"` + - `array of object { end_index, start_index, title, 2 more }` - - `Grammar object { definition, syntax, type }` + - `end_index: number` - A grammar defined by the user. + The index of the last character of the citation in the message. - - `definition: string` + - `start_index: number` - The grammar definition. + The index of the first character of the citation in the message. - - `syntax: "lark" or "regex"` + - `title: string` - The syntax of the grammar definition. One of `lark` or `regex`. + The title of the cited resource. - - `"lark"` + - `type: "url_citation"` - - `"regex"` + The citation type. Always `url_citation`. - - `type: "grammar"` + - `"url_citation"` - Grammar format. Always `grammar`. + - `url: string` - - `"grammar"` + The URL of the cited resource. - - `type: "namespace"` + - `array of object { container_id, end_index, file_id, 3 more }` - The type of the tool. Always `namespace`. + - `container_id: string` - - `"namespace"` + The ID of the container. - - `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 citation in the message. - - `type: "tool_search"` + - `file_id: string` - The type of the tool. Always `tool_search`. + The ID of the container 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 citation in the message. - Whether tool search is executed by the server or by the client. + - `type: "container_file_citation"` - - `"server"` + The citation type. Always `container_file_citation`. - - `"client"` + - `"container_file_citation"` - - `parameters: optional unknown` + - `type: "multi_agent_call_output"` - Parameter schema for a client-executed tool search tool. + The item type. Always `multi_agent_call_output`. - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + - `"multi_agent_call_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). + - `id: optional string` - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + The unique ID of this multi-agent call output. - 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"` + - `ToolSearchCall object { arguments, type, id, 4 more }` - - `"image"` + - `arguments: unknown` - - `search_context_size: optional "low" or "medium" or "high"` + The arguments supplied to the tool search 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: "tool_search_call"` - - `"low"` + The item type. Always `tool_search_call`. - - `"medium"` + - `"tool_search_call"` - - `"high"` + - `id: optional string` - - `user_location: optional object { type, city, country, 2 more }` + The unique ID of this tool search 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` + - `call_id: optional string` - Free text input for the city of the user, e.g. `San Francisco`. + The unique ID of the tool search call generated by the model. - - `country: optional string` + - `execution: optional "server" or "client"` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + Whether tool search was executed by the server or by the client. - - `region: optional string` + - `"server"` - Free text input for the region of the user, e.g. `California`. + - `"client"` - - `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 tool search call. - - `ApplyPatch object { type, allowed_callers }` + - `"in_progress"` - Allows the assistant to create, delete, or update files using unified diffs. + - `"completed"` - - `type: "apply_patch"` + - `"incomplete"` - The type of the tool. Always `apply_patch`. + - `ToolSearchOutput object { tools, type, id, 4 more }` - - `"apply_patch"` + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - - `allowed_callers: optional array of "direct" or "programmatic"` + The loaded tool definitions returned by the tool search output. - The tool invocation context(s). + - `Function object { name, parameters, strict, 5 more }` - - `"direct"` + 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). - - `"programmatic"` + - `name: string` - - `type: "additional_tools"` + The name of the function to call. - The type of the item. Always `additional_tools`. + - `parameters: map[unknown]` - - `"additional_tools"` + A JSON schema object describing the parameters of the function. - - `agent: optional object { agent_name }` + - `strict: boolean` - The agent that produced this item. + 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`. - - `Compaction object { id, encrypted_content, type, 2 more }` + - `"function"` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `allowed_callers: optional array of "direct" or "programmatic"` - - `id: string` + The tool invocation context(s). - The unique ID of the compaction item. + - `"direct"` - - `encrypted_content: string` + - `"programmatic"` - The encrypted content that was produced by compaction. + - `defer_loading: optional boolean` - - `type: "compaction"` + Whether this function is deferred and loaded via tool search. - The type of the item. Always `compaction`. + - `description: optional string` - - `"compaction"` + 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). - - `created_by: optional string` + - `type: "file_search"` - The identifier of the actor that created the item. + The type of the file search tool. Always `file_search`. - - `ImageGenerationCall object { id, result, status, 2 more }` + - `"file_search"` - An image generation request made by the model. + - `vector_store_ids: array of string` - - `id: string` + The IDs of the vector stores to search. - The unique ID of the image generation call. + - `filters: optional object { key, type, value } or object { filters, type }` - - `result: string` + A filter to apply. - The generated image encoded in base64. + - `ComparisonFilter object { key, type, value }` - - `status: "in_progress" or "completed" or "generating" or "failed"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The status of the image generation call. + - `key: string` - - `"in_progress"` + The key to compare against the value. - - `"completed"` + - `type: "eq" or "ne" or "gt" or 5 more` - - `"generating"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `"failed"` + - `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: "image_generation_call"` + - `"eq"` - The type of the image generation call. Always `image_generation_call`. + - `"ne"` - - `"image_generation_call"` + - `"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"` - - `CodeInterpreterCall object { id, code, container_id, 4 more }` + - `"nin"` - A tool call to run code. + - `value: string or number or boolean or array of string or number` - - `id: string` + The value to compare against the attribute key; supports string, number, or boolean types. - The unique ID of the code interpreter tool call. + - `string` - - `code: string` + - `number` - The code to run, or null if not available. + - `boolean` - - `container_id: string` + - `array of string or number` - The ID of the container used to run the code. + - `string` - - `outputs: array of object { logs, type } or object { type, url }` + - `number` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `CompoundFilter object { filters, type }` - - `Logs object { logs, type }` + Combine multiple filters using `and` or `or`. - The logs output from the code interpreter. + - `filters: array of object { key, type, value } or unknown` - - `logs: string` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - 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` + - `unknown` - The canonical name of the agent that produced this item. + - `type: "and" or "or"` + + Type of operation: `and` or `or`. + + - `"and"` + + - `"or"` - - `LocalShellCall object { id, action, call_id, 3 more }` + - `max_num_results: optional number` - A tool call to run a command on the local shell. + 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 local shell call. + Ranking options for search. - - `action: object { command, env, type, 3 more }` + - `hybrid_search: optional object { embedding_weight, text_weight }` - Execute a shell command on the server. + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `command: array of string` + - `embedding_weight: number` - The command to run. + The weight of the embedding in the reciprocal ranking fusion. - - `env: map[string]` + - `text_weight: number` - Environment variables to set for the command. + The weight of the text in the reciprocal ranking fusion. - - `type: "exec"` + - `ranker: optional "auto" or "default-2024-11-15"` - The type of the local shell action. Always `exec`. + The ranker to use for the file search. - - `"exec"` + - `"auto"` - - `timeout_ms: optional number` + - `"default-2024-11-15"` - Optional timeout in milliseconds for the command. + - `score_threshold: optional number` - - `user: optional string` + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - Optional user to run the command as. + - `Computer object { type }` - - `working_directory: 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 working directory to run the command in. + - `type: "computer"` - - `call_id: string` + The type of the computer tool. Always `computer`. - The unique ID of the local shell tool call generated by the model. + - `"computer"` - - `status: "in_progress" or "completed" or "incomplete"` + - `ComputerUsePreview object { display_height, display_width, environment, type }` - The status of the local shell call. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"in_progress"` + - `display_height: number` - - `"completed"` + The height of the computer display. - - `"incomplete"` + - `display_width: number` - - `type: "local_shell_call"` + The width of the computer display. - The type of the local shell call. Always `local_shell_call`. + - `environment: "windows" or "mac" or "linux" or 2 more` - - `"local_shell_call"` + The type of computer environment to control. - - `agent: optional object { agent_name }` + - `"windows"` - The agent that produced this item. + - `"mac"` - - `agent_name: string` + - `"linux"` - The canonical name of the agent that produced this item. + - `"ubuntu"` - - `LocalShellCallOutput object { id, output, type, 2 more }` + - `"browser"` - The output of a local shell tool call. + - `type: "computer_use_preview"` - - `id: string` + The type of the computer use tool. Always `computer_use_preview`. - The unique ID of the local shell tool call generated by the model. + - `"computer_use_preview"` - - `output: string` + - `WebSearch object { type, filters, search_context_size, user_location }` - A JSON string of the output of the local shell tool call. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - - `type: "local_shell_call_output"` + - `type: "web_search" or "web_search_2025_08_26"` - The type of the local shell tool call output. Always `local_shell_call_output`. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `"local_shell_call_output"` + - `"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` - - `status: optional "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`. + 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"` - - `ShellCall object { id, action, call_id, 6 more }` + - `"medium"` - A tool call that executes one or more shell commands in a managed environment. + - `"high"` - - `id: string` + - `user_location: optional object { city, country, region, 2 more }` - The unique ID of the shell tool call. Populated when this item is returned via API. + The approximate location of the user. - - `action: object { commands, max_output_length, timeout_ms }` + - `city: optional string` - The shell commands and limits that describe how to run the tool call. + Free text input for the city of the user, e.g. `San Francisco`. - - `commands: array of string` + - `country: optional string` - - `max_output_length: number` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - Optional maximum number of characters to return from each command. + - `region: optional string` - - `timeout_ms: number` + Free text input for the region of the user, e.g. `California`. - Optional timeout in milliseconds for the commands. + - `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"` - - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` + The type of location approximation. Always `approximate`. - Represents the use of a local environment to perform shell actions. + - `"approximate"` - - `BetaResponseLocalEnvironment object { type }` + - `Mcp object { server_label, type, allowed_callers, 9 more }` - Represents the use of a local environment to perform shell actions. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - - `type: "local"` + - `server_label: string` - The environment type. Always `local`. + A label for this MCP server, used to identify it in tool calls. - - `"local"` + - `type: "mcp"` - - `BetaResponseContainerReference object { container_id, type }` + The type of the MCP tool. Always `mcp`. - Represents a container created with /v1/containers. + - `"mcp"` - - `container_id: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `type: "container_reference"` + The tool invocation context(s). - The environment type. Always `container_reference`. + - `"direct"` - - `"container_reference"` + - `"programmatic"` - - `status: "in_progress" or "completed" or "incomplete"` + - `allowed_tools: optional array of string or object { read_only, tool_names }` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + List of allowed tool names or a filter object. - - `"in_progress"` + - `McpAllowedTools = array of string` - - `"completed"` + A string array of allowed tool names - - `"incomplete"` + - `McpToolFilter object { read_only, tool_names }` - - `type: "shell_call"` + A filter object to specify which tools are allowed. - The type of the item. Always `shell_call`. + - `read_only: optional boolean` - - `"shell_call"` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `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"` - - `created_by: optional string` + - `"connector_outlookemail"` - The ID of the entity that created this tool call. + - `"connector_sharepoint"` - - `ShellCallOutput object { id, call_id, max_output_length, 6 more }` + - `defer_loading: optional boolean` - The output of a shell tool call that was emitted. + Whether this MCP tool is deferred and discovered via tool search. - - `id: string` + - `headers: optional map[string]` - The unique ID of the shell call output. Populated when this item is returned via API. + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `call_id: string` + - `require_approval: optional object { always, never } or "always" or "never"` - The unique ID of the shell tool call generated by the model. + Specify which of the MCP server's tools require approval. - - `max_output_length: number` + - `McpToolApprovalFilter object { always, never }` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw 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. - - `output: array of object { outcome, stderr, stdout, created_by }` + - `always: optional 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"` + - `never: optional object { read_only, tool_names }` - The outcome type. Always `timeout`. + A filter object to specify which tools are allowed. - - `"timeout"` + - `read_only: optional boolean` - - `Exit object { exit_code, 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. - Indicates that the shell commands finished and returned an exit code. + - `tool_names: optional array of string` - - `exit_code: number` + List of allowed tool names. - Exit code from the shell process. + - `McpToolApprovalSetting = "always" or "never"` - - `type: "exit"` + 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 outcome type. Always `exit`. + - `"always"` - - `"exit"` + - `"never"` - - `stderr: string` + - `server_description: optional string` - The standard error output that was captured. + Optional description of the MCP server, used to provide more context. - - `stdout: string` + - `server_url: optional string` - The standard output that was captured. + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `created_by: optional string` + - `tunnel_id: optional string` - The identifier of the actor that created the 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: "in_progress" or "completed" or "incomplete"` + - `CodeInterpreter object { container, type, allowed_callers }` - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + 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: "shell_call_output"` + The container ID. - The type of the shell call output. Always `shell_call_output`. + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - - `"shell_call_output"` + 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"` - - `"direct"` + - `"4g"` - - `Program object { caller_id, type }` + - `"16g"` - - `caller_id: string` + - `"64g"` - The call ID of the program item that produced this tool call. + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `type: "program"` + Network access policy for the container. - - `"program"` + - `BetaContainerNetworkPolicyDisabled object { type }` - - `created_by: optional string` + - `type: "disabled"` - The identifier of the actor that created the item. + Disable outbound network access. Always `disabled`. - - `ApplyPatchCall object { id, call_id, operation, 5 more }` + - `"disabled"` - A tool call that applies file diffs by creating, deleting, or updating files. + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `id: string` + - `allowed_domains: array of string` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + A list of allowed domains when type is `allowlist`. - - `call_id: string` + - `type: "allowlist"` - The unique ID of the apply patch tool call generated by the model. + Allow outbound network access only to specified domains. Always `allowlist`. - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + - `"allowlist"` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` - - `CreateFile object { diff, path, type }` + Optional domain-scoped secrets for allowlisted domains. - Instruction describing how to create a file via the apply_patch tool. + - `domain: string` - - `diff: string` + The domain associated with the secret. - Diff to apply. + - `name: string` - - `path: string` + The name of the secret to inject for the domain. - Path of the file to create. + - `value: string` - - `type: "create_file"` + The secret value to inject for the domain. - Create a new file with the provided diff. + - `type: "code_interpreter"` - - `"create_file"` + The type of the code interpreter tool. Always `code_interpreter`. - - `DeleteFile object { path, type }` + - `"code_interpreter"` - Instruction describing how to delete a file via the apply_patch tool. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `path: string` + The tool invocation context(s). - Path of the file to delete. + - `"direct"` - - `type: "delete_file"` + - `"programmatic"` - Delete the specified file. + - `ProgrammaticToolCalling object { type }` - - `"delete_file"` + - `type: "programmatic_tool_calling"` - - `UpdateFile object { diff, path, type }` + The type of the tool. Always `programmatic_tool_calling`. - Instruction describing how to update a file via the apply_patch tool. + - `"programmatic_tool_calling"` - - `diff: string` + - `ImageGeneration object { type, action, background, 9 more }` - Diff to apply. + A tool that generates images using the GPT image models. - - `path: string` + - `type: "image_generation"` - Path of the file to update. + The type of the image generation tool. Always `image_generation`. - - `type: "update_file"` + - `"image_generation"` - Update an existing file with the provided diff. + - `action: optional "generate" or "edit" or "auto"` - - `"update_file"` + Whether to generate a new image or edit an existing image. Default: `auto`. - - `status: "in_progress" or "completed"` + - `"generate"` - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `"edit"` - - `"in_progress"` + - `"auto"` - - `"completed"` + - `background: optional "transparent" or "opaque" or "auto"` - - `type: "apply_patch_call"` + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - The type of the item. Always `apply_patch_call`. + - `"transparent"` - - `"apply_patch_call"` + - `"opaque"` - - `agent: optional object { agent_name }` + - `"auto"` - The agent that produced this item. + - `input_fidelity: optional "high" or "low"` - - `agent_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 canonical name of the agent that produced this item. + - `"high"` - - `caller: optional object { type } or object { caller_id, type }` + - `"low"` - The execution context that produced this tool call. + - `input_image_mask: optional object { file_id, image_url }` - - `Direct object { type }` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `type: "direct"` + - `file_id: optional string` - - `"direct"` + File ID for the mask image. - - `Program object { caller_id, type }` + - `image_url: optional string` - - `caller_id: string` + Base64-encoded mask image. - The call ID of the program item that produced this tool call. + - `model: optional string or "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`. - - `"program"` + - `string` - - `created_by: optional string` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - The ID of the entity that created this tool call. + The image generation model to use. Default: `gpt-image-1`. - - `ApplyPatchCallOutput object { id, call_id, status, 5 more }` + - `"gpt-image-1"` - The output emitted by an apply patch tool call. + - `"gpt-image-1-mini"` - - `id: string` + - `"gpt-image-1.5"` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `moderation: optional "auto" or "low"` - - `call_id: string` + Moderation level for the generated image. Default: `auto`. - The unique ID of the apply patch tool call generated by the model. + - `"auto"` - - `status: "completed" or "failed"` + - `"low"` - The status of the apply patch tool call output. One of `completed` or `failed`. + - `output_compression: optional number` - - `"completed"` + Compression level for the output image. Default: 100. - - `"failed"` + - `output_format: optional "png" or "webp" or "jpeg"` - - `type: "apply_patch_call_output"` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - The type of the item. Always `apply_patch_call_output`. + - `"png"` - - `"apply_patch_call_output"` + - `"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"` - - `caller: optional object { type } or object { caller_id, type }` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - The execution context that produced this tool call. + - `"low"` - - `Direct object { type }` + - `"medium"` - - `type: "direct"` + - `"high"` - - `"direct"` + - `"auto"` - - `Program object { caller_id, type }` + - `size: optional string or "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. + - `string` - - `type: "program"` + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `"program"` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `created_by: optional string` + - `"1024x1024"` - The ID of the entity that created this tool call output. + - `"1024x1536"` - - `output: optional string` + - `"1536x1024"` - Optional textual output returned by the apply patch tool. + - `"auto"` - - `McpCall object { id, arguments, name, 7 more }` + - `LocalShell object { type }` - An invocation of a tool on an MCP server. + A tool that allows the model to execute shell commands in a local environment. - - `id: string` + - `type: "local_shell"` - The unique ID of the tool call. + The type of the local shell tool. Always `local_shell`. - - `arguments: string` + - `"local_shell"` - A JSON string of the arguments passed to the tool. + - `Shell object { type, allowed_callers, environment }` - - `name: string` + A tool that allows the model to execute shell commands. - The name of the tool that was run. + - `type: "shell"` - - `server_label: string` + The type of the shell tool. Always `shell`. - The label of the MCP server running the tool. + - `"shell"` - - `type: "mcp_call"` + - `allowed_callers: optional array of "direct" or "programmatic"` - The type of the item. Always `mcp_call`. + The tool invocation context(s). - - `"mcp_call"` + - `"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. + - `type: "container_auto"` - - `approval_request_id: optional string` + Automatically creates a container for this request - 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. + - `"container_auto"` - - `error: optional string` + - `file_ids: optional array of string` - The error from the tool call, if any. + An optional list of uploaded files to make available to your code. - - `output: optional string` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - The output from the tool call. + The memory limit for the container. - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `"1g"` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `"4g"` - - `"in_progress"` + - `"16g"` - - `"completed"` + - `"64g"` - - `"incomplete"` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `"calling"` + Network access policy for the container. - - `"failed"` + - `BetaContainerNetworkPolicyDisabled object { type }` - - `McpListTools object { id, server_label, tools, 3 more }` + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - A list of tools available on an MCP server. + - `skills: optional array of BetaSkillReference or BetaInlineSkill` - - `id: string` + An optional list of skills referenced by id or inline data. - The unique ID of the list. + - `BetaSkillReference object { skill_id, type, version }` - - `server_label: string` + - `skill_id: string` - The label of the MCP server. + The ID of the referenced skill. - - `tools: array of object { input_schema, name, annotations, description }` + - `type: "skill_reference"` - The tools available on the server. + References a skill created with the /v1/skills endpoint. - - `input_schema: unknown` + - `"skill_reference"` - The JSON schema describing the tool's input. + - `version: optional string` - - `name: string` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - The name of the tool. + - `BetaInlineSkill object { description, name, source, type }` - - `annotations: optional unknown` + - `description: string` - Additional annotations about the tool. + The description of the skill. - - `description: optional string` + - `name: string` - The description of the tool. + The name of the skill. - - `type: "mcp_list_tools"` + - `source: BetaInlineSkillSource` - The type of the item. Always `mcp_list_tools`. + Inline skill payload - - `"mcp_list_tools"` + - `data: string` - - `agent: optional object { agent_name }` + Base64-encoded skill zip bundle. - The agent that produced this item. + - `media_type: "application/zip"` - - `agent_name: string` + The media type of the inline skill payload. Must be `application/zip`. - The canonical name of the agent that produced this item. + - `"application/zip"` - - `error: optional string` + - `type: "base64"` - Error message if the server could not list tools. + The type of the inline skill source. Must be `base64`. - - `McpApprovalRequest object { id, arguments, name, 3 more }` + - `"base64"` - A request for human approval of a tool invocation. + - `type: "inline"` - - `id: string` + Defines an inline skill for this request. - The unique ID of the approval request. + - `"inline"` - - `arguments: string` + - `BetaLocalEnvironment object { type, skills }` - A JSON string of arguments for the tool. + - `type: "local"` - - `name: string` + Use a local computer environment. - The name of the tool to run. + - `"local"` - - `server_label: string` + - `skills: optional array of BetaLocalSkill` - The label of the MCP server making the request. + An optional list of skills. - - `type: "mcp_approval_request"` + - `description: string` - The type of the item. Always `mcp_approval_request`. + The description of the skill. - - `"mcp_approval_request"` + - `name: string` - - `agent: optional object { agent_name }` + The name of the skill. - The agent that produced this item. + - `path: string` - - `agent_name: string` + The path to the directory containing the skill. - The canonical name of the agent that produced this item. + - `BetaContainerReference object { container_id, type }` - - `McpApprovalResponse object { id, approval_request_id, approve, 3 more }` + - `container_id: string` - A response to an MCP approval request. + The ID of the referenced container. - - `id: string` + - `type: "container_reference"` - The unique ID of the approval response + References a container created with the /v1/containers endpoint - - `approval_request_id: string` + - `"container_reference"` - The ID of the approval request being answered. + - `Custom object { name, type, allowed_callers, 3 more }` - - `approve: boolean` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - Whether the request was approved. + - `name: string` - - `type: "mcp_approval_response"` + The name of the custom tool, used to identify it in tool calls. - The type of the item. Always `mcp_approval_response`. + - `type: "custom"` - - `"mcp_approval_response"` + 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"` - - `reason: optional string` + - `"programmatic"` - Optional reason for the decision. + - `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"` + - `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` - - `"program"` + The namespace name used in tool calls (for example, `crm`). - - `namespace: optional string` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - The namespace of the custom tool being called. + The function/custom tools available inside this namespace. - - `CustomToolCallOutput object { id, call_id, output, 5 more }` + - `Function object { name, type, allowed_callers, 5 more }` - - `id: string` + - `name: string` - The unique ID of the custom tool call output item. + - `type: "function"` - - `call_id: string` + - `"function"` - The call ID, used to map this custom tool call output to a custom tool call. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + The tool invocation context(s). - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `"direct"` - - `StringOutput = string` + - `"programmatic"` - A string of the output of the custom tool call. + - `defer_loading: optional boolean` - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + Whether this function should be deferred and discovered via tool search. - Text, image, or file output of the custom tool call. + - `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](https://platform.openai.com/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 }` - - `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: "custom_tool_call_output"` + - `"custom"` - The type of the custom tool call output. Always `custom_tool_call_output`. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"custom_tool_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"` - - `parallel_tool_calls: boolean` + The syntax of the grammar definition. One of `lark` or `regex`. - Whether to allow the model to run tool calls in parallel. + - `"lark"` - - `temperature: number` + - `"regex"` - 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: "grammar"` - - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` + Grammar format. Always `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. + - `"grammar"` - - `BetaToolChoiceOptions = "none" or "auto" or "required"` + - `type: "namespace"` - Controls which (if any) tool is called by the model. + The type of the tool. Always `namespace`. - `none` means the model will not call any tool and instead generates a message. + - `"namespace"` - `auto` means the model can pick between generating a message or calling one or - more tools. + - `ToolSearch object { type, description, execution, parameters }` - `required` means the model must call one or more tools. + Hosted or BYOT tool search configuration for deferred tools. - - `"none"` + - `type: "tool_search"` - - `"auto"` + The type of the tool. Always `tool_search`. - - `"required"` + - `"tool_search"` - - `BetaToolChoiceAllowed object { mode, tools, type }` + - `description: optional string` - Constrains the tools available to the model to a pre-defined set. + Description shown to the model for a client-executed tool search tool. - - `mode: "auto" or "required"` + - `execution: optional "server" or "client"` - Constrains the tools available to the model to a pre-defined set. + Whether tool search is executed by the server or by the client. - `auto` allows the model to pick from among the allowed tools and generate a - message. + - `"server"` - `required` requires the model to call one or more of the allowed tools. + - `"client"` - - `"auto"` + - `parameters: optional unknown` - - `"required"` + Parameter schema for a client-executed tool search tool. - - `tools: array of map[unknown]` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - A list of tool definitions that the model should be allowed to 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). - For the Responses API, the list of tool definitions might look like: + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `type: "allowed_tools"` + - `"web_search_preview"` - Allowed tool configuration type. Always `allowed_tools`. + - `"web_search_preview_2025_03_11"` - - `"allowed_tools"` + - `search_content_types: optional array of "text" or "image"` - - `BetaToolChoiceTypes object { type }` + - `"text"` - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + - `"image"` - - `type: "file_search" or "web_search_preview" or "computer" or 5 more` + - `search_context_size: optional "low" or "medium" or "high"` - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + 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. - Allowed values are: + - `"low"` - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + - `"medium"` - - `"file_search"` + - `"high"` - - `"web_search_preview"` + - `user_location: optional object { type, city, country, 2 more }` - - `"computer"` + The user's location. - - `"computer_use_preview"` + - `type: "approximate"` - - `"computer_use"` + The type of location approximation. Always `approximate`. - - `"web_search_preview_2025_03_11"` + - `"approximate"` - - `"image_generation"` + - `city: optional string` - - `"code_interpreter"` + Free text input for the city of the user, e.g. `San Francisco`. - - `BetaToolChoiceFunction object { name, type }` + - `country: optional string` - Use this option to force the model to call a specific function. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `name: string` + - `region: optional string` - The name of the function to call. + Free text input for the region of the user, e.g. `California`. - - `type: "function"` + - `timezone: optional string` - For function calling, the type is always `function`. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `"function"` + - `ApplyPatch object { type, allowed_callers }` - - `BetaToolChoiceMcp object { server_label, type, name }` + Allows the assistant to create, delete, or update files using unified diffs. - Use this option to force the model to call a specific tool on a remote MCP server. + - `type: "apply_patch"` - - `server_label: string` + The type of the tool. Always `apply_patch`. - The label of the MCP server to use. + - `"apply_patch"` - - `type: "mcp"` + - `allowed_callers: optional array of "direct" or "programmatic"` - For MCP tools, the type is always `mcp`. + The tool invocation context(s). - - `"mcp"` + - `"direct"` - - `name: optional string` + - `"programmatic"` - The name of the tool to call on the server. + - `type: "tool_search_output"` - - `BetaToolChoiceCustom object { name, type }` + The item type. Always `tool_search_output`. - Use this option to force the model to call a specific custom tool. + - `"tool_search_output"` - - `name: string` + - `id: optional string` - The name of the custom tool to call. + The unique ID of this tool search 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` - - `BetaSpecificProgrammaticToolCallingParam object { type }` + The canonical name of the agent that produced this item. - - `type: "programmatic_tool_calling"` + - `call_id: optional string` - The tool to call. Always `programmatic_tool_calling`. + The unique ID of the tool search call generated by the model. - - `"programmatic_tool_calling"` + - `execution: optional "server" or "client"` - - `BetaToolChoiceApplyPatch object { type }` + Whether tool search was executed by the server or by the client. - Forces the model to call the apply_patch tool when executing a tool call. + - `"server"` - - `type: "apply_patch"` + - `"client"` - The tool to call. Always `apply_patch`. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"apply_patch"` + The status of the tool search output. - - `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`. + - `AdditionalTools object { role, tools, type, 2 more }` - - `"shell"` + - `role: "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 role that provided the additional tools. Only `developer` is supported. - 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. + - `"developer"` - 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](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/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](https://platform.openai.com/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](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. + A list of additional tools made available at this item. - `Function object { name, parameters, strict, 5 more }` @@ -132076,7 +129981,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-web-search). + [web search tool](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -132136,7 +130041,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -132188,7 +130093,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -132380,19 +130285,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `background: optional "transparent" or "opaque" or "auto"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. - - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. - - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - `"transparent"` @@ -132421,13 +130315,13 @@ curl -X POST https://api.openai.com/v1/responses/compact \ Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `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-2" or 3 more` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` The image generation model to use. Default: `gpt-image-1`. @@ -132435,14 +130329,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"gpt-image-1-mini"` - - `"gpt-image-2"` - - - `"gpt-image-2-2026-04-21"` - - `"gpt-image-1.5"` - - `"chatgpt-image-latest"` - - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -132539,7 +130427,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -132653,7 +130541,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -132687,989 +130575,1207 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `Text object { type }` - Unconstrained free-form text. + 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 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 - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `Compaction object { encrypted_content, type, id, 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. - - `type: "text"` + - `outputs: array of object { logs, type } or object { type, url }` - Unconstrained text format. Always `text`. + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `"text"` + - `Logs object { logs, type }` - - `Grammar object { definition, syntax, type }` + The logs output from the code interpreter. - A grammar defined by the user. + - `logs: string` - - `definition: string` + The logs output from the code interpreter. - The grammar definition. + - `type: "logs"` - - `syntax: "lark" or "regex"` + The type of the output. Always `logs`. - The syntax of the grammar definition. One of `lark` or `regex`. + - `"logs"` - - `"lark"` + - `Image object { type, url }` - - `"regex"` + The image output from the code interpreter. - - `type: "grammar"` + - `type: "image"` - Grammar format. Always `grammar`. + The type of the output. Always `image`. - - `"grammar"` + - `"image"` - - `type: "namespace"` + - `url: string` - The type of the tool. Always `namespace`. + The URL of the image output from the code interpreter. - - `"namespace"` + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - - `ToolSearch object { type, description, execution, parameters }` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - Hosted or BYOT tool search configuration for deferred tools. + - `"in_progress"` - - `type: "tool_search"` + - `"completed"` - The type of the tool. Always `tool_search`. + - `"incomplete"` - - `"tool_search"` + - `"interpreting"` - - `description: optional string` + - `"failed"` - Description shown to the model for a client-executed tool search tool. + - `type: "code_interpreter_call"` - - `execution: optional "server" or "client"` + The type of the code interpreter tool call. Always `code_interpreter_call`. - Whether tool search is executed by the server or by the client. + - `"code_interpreter_call"` - - `"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 }` + - `LocalShellCall object { id, action, call_id, 3 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 tool call to run a command on the local shell. - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `id: string` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + The unique ID of the local shell call. - - `"web_search_preview"` + - `action: object { command, env, type, 3 more }` - - `"web_search_preview_2025_03_11"` + Execute a shell command on the server. - - `search_content_types: optional array of "text" or "image"` + - `command: array of string` - - `"text"` + The command to run. - - `"image"` + - `env: map[string]` - - `search_context_size: optional "low" or "medium" or "high"` + Environment variables to set for the command. - 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: "exec"` - - `"low"` + The type of the local shell action. Always `exec`. - - `"medium"` + - `"exec"` - - `"high"` + - `timeout_ms: optional number` - - `user_location: optional object { type, city, country, 2 more }` + Optional timeout in milliseconds for the command. - The user's location. + - `user: optional string` - - `type: "approximate"` + Optional user to run the command as. - The type of location approximation. Always `approximate`. + - `working_directory: optional string` - - `"approximate"` + Optional working directory to run the command in. - - `city: optional string` + - `call_id: string` - Free text input for the city of the user, e.g. `San Francisco`. + The unique ID of the local shell tool call generated by the model. - - `country: optional string` + - `status: "in_progress" or "completed" or "incomplete"` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The status of the local shell call. - - `region: optional string` + - `"in_progress"` - Free text input for the region of the user, e.g. `California`. + - `"completed"` - - `timezone: optional string` + - `"incomplete"` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `type: "local_shell_call"` - - `ApplyPatch object { type, allowed_callers }` + The type of the local shell call. Always `local_shell_call`. - Allows the assistant to create, delete, or update files using unified diffs. + - `"local_shell_call"` - - `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). + - `LocalShellCallOutput object { id, output, type, 2 more }` - - `"direct"` + The output of a local shell tool call. - - `"programmatic"` + - `id: string` - - `top_p: number` + The unique ID of the local shell tool call generated by 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. + - `output: string` - We generally recommend altering this or `temperature` but not both. + A JSON string of the output of the local shell tool call. - - `background: optional boolean` + - `type: "local_shell_call_output"` - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + The type of the local shell tool call output. Always `local_shell_call_output`. - - `completed_at: optional number` + - `"local_shell_call_output"` - 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 item. One of `in_progress`, `completed`, or `incomplete`. - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/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 }` + - `ShellCall object { action, call_id, type, 5 more }` - Moderation results for the response input and output, if moderated completions were requested. + A tool representing a request to execute one or more shell commands. - - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + - `action: object { commands, max_output_length, timeout_ms }` - Moderation for the response input. + The shell commands and limits that describe how to run the tool call. - - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` + - `commands: array of string` - A moderation result produced for the response input or output. + Ordered shell commands for the execution environment to run. - - `categories: map[boolean]` + - `max_output_length: optional number` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - - `category_applied_input_types: map[array of "text" or "image"]` + - `timeout_ms: optional number` - Which modalities of input are reflected by the score for each category. + Maximum wall-clock time in milliseconds to allow the shell commands to run. - - `"text"` + - `call_id: string` - - `"image"` + The unique ID of the shell tool call generated by the model. - - `category_scores: map[number]` + - `type: "shell_call"` - A dictionary of moderation categories to scores. + The type of the item. Always `shell_call`. - - `flagged: boolean` + - `"shell_call"` - A boolean indicating whether the content was flagged by any category. + - `id: optional string` - - `model: string` + The unique ID of the shell tool call. Populated when this item is returned via API. - The moderation model that produced this result. + - `agent: optional object { agent_name }` - - `type: "moderation_result"` + The agent that produced this item. - The object type, which was always `moderation_result` for successful moderation results. + - `agent_name: string` - - `"moderation_result"` + The canonical name of the agent that produced this item. - - `Error object { code, message, type }` + - `caller: optional object { type } or object { caller_id, type }` - An error produced while attempting moderation for the response input or output. + The execution context that produced this tool call. - - `code: string` + - `Direct object { type }` - The error code. + - `type: "direct"` - - `message: string` + The caller type. Always `direct`. - The error message. + - `"direct"` - - `type: "error"` + - `Program object { caller_id, type }` - The object type, which was always `error` for moderation failures. + - `caller_id: string` - - `"error"` + The call ID of the program item that produced this tool call. - - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + - `type: "program"` - Moderation for the response output. + The caller type. Always `program`. - - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` + - `"program"` - A moderation result produced for the response input or output. + - `environment: optional BetaLocalEnvironment or BetaContainerReference` - - `categories: map[boolean]` + The environment to execute the shell commands in. - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `BetaLocalEnvironment object { type, skills }` - - `category_applied_input_types: map[array of "text" or "image"]` + - `BetaContainerReference object { container_id, type }` - Which modalities of input are reflected by the score for each category. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"text"` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `"image"` + - `"in_progress"` - - `category_scores: map[number]` + - `"completed"` - A dictionary of moderation categories to scores. + - `"incomplete"` - - `flagged: boolean` + - `ShellCallOutput object { call_id, output, type, 5 more }` - A boolean indicating whether the content was flagged by any category. + The streamed output items emitted by a shell tool call. - - `model: string` + - `call_id: string` - The moderation model that produced this result. + The unique ID of the shell tool call generated by the model. - - `type: "moderation_result"` + - `output: array of BetaResponseFunctionShellCallOutputContent` - The object type, which was always `moderation_result` for successful moderation results. + Captured chunks of stdout and stderr output, along with their associated outcomes. - - `"moderation_result"` + - `outcome: object { type } or object { exit_code, type }` - - `Error object { code, message, type }` + The exit or timeout outcome associated with this shell call. - An error produced while attempting moderation for the response input or output. + - `Timeout object { type }` - - `code: string` + Indicates that the shell call exceeded its configured time limit. - The error code. + - `type: "timeout"` - - `message: string` + The outcome type. Always `timeout`. - The error message. + - `"timeout"` - - `type: "error"` + - `Exit object { exit_code, type }` - The object type, which was always `error` for moderation failures. + Indicates that the shell commands finished and returned an exit code. - - `"error"` + - `exit_code: number` - - `previous_response_id: optional string` + The exit code returned by the shell process. - The unique ID of the previous response to the model. Use this to - create multi-turn conversations. Learn more about - [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + - `type: "exit"` - - `prompt: optional BetaResponsePrompt` + The outcome type. Always `exit`. - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + - `"exit"` - - `id: string` + - `stderr: string` - The unique identifier of the prompt template to use. + Captured stderr output for the shell call. - - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` + - `stdout: 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. + Captured stdout output for the shell call. - - `string` + - `type: "shell_call_output"` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + The type of the item. Always `shell_call_output`. - A text input to the model. + - `"shell_call_output"` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `id: optional string` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The unique ID of the shell tool call output. Populated when this item is returned via API. - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `agent: optional object { agent_name }` - A file input to the model. + The agent that produced this item. - - `version: optional string` + - `agent_name: string` - Optional version of the prompt template. + The canonical name of the agent that produced this item. - - `prompt_cache_key: optional string` + - `caller: optional object { type } or object { caller_id, type }` - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + The execution context that produced this tool call. - - `prompt_cache_options: optional object { mode, ttl }` + - `Direct object { type }` - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + - `type: "direct"` - - `mode: "implicit" or "explicit"` + The caller type. Always `direct`. - Whether implicit prompt-cache breakpoints were enabled. + - `"direct"` - - `"implicit"` + - `Program object { caller_id, type }` - - `"explicit"` + - `caller_id: string` - - `ttl: "30m"` + The call ID of the program item that produced this tool call. - The minimum lifetime applied to each cache breakpoint. + - `type: "program"` - - `"30m"` + The caller type. Always `program`. - - `prompt_cache_retention: optional "in_memory" or "24h"` + - `"program"` - Deprecated. Use `prompt_cache_options.ttl` instead. + - `max_output_length: 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](https://platform.openai.com/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 maximum number of UTF-8 characters captured for this shell call's combined output. - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + - `status: optional "in_progress" or "completed" or "incomplete"` - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + The status of the shell call output. - - `"in_memory"` + - `"in_progress"` - - `"24h"` + - `"completed"` - - `reasoning: optional object { context, effort, generate_summary, 2 more }` + - `"incomplete"` - **gpt-5 and o-series models only** + - `ApplyPatchCall object { call_id, operation, status, 4 more }` - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + A tool call representing a request to create, delete, or update files using diff patches. - - `context: optional "auto" or "current_turn" or "all_turns"` + - `call_id: string` - Controls which reasoning items are rendered back to the model on later turns. - When returned on a response, this is the effective reasoning context mode - used for the response. + The unique ID of the apply patch tool call generated by the model. - - `"auto"` + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - - `"current_turn"` + The specific create, delete, or update instruction for the apply_patch tool call. - - `"all_turns"` + - `CreateFile object { diff, path, type }` - - `effort: optional "none" or "minimal" or "low" or 4 more` + Instruction for creating a new file via the apply_patch 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. + - `diff: string` - - `"none"` + Unified diff content to apply when creating the file. - - `"minimal"` + - `path: string` - - `"low"` + Path of the file to create relative to the workspace root. - - `"medium"` + - `type: "create_file"` - - `"high"` + The operation type. Always `create_file`. - - `"xhigh"` + - `"create_file"` - - `"max"` + - `DeleteFile object { path, type }` - - `generate_summary: optional "auto" or "concise" or "detailed"` + Instruction for deleting an existing file via the apply_patch tool. - **Deprecated:** use `summary` instead. + - `path: 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`. + Path of the file to delete relative to the workspace root. - - `"auto"` + - `type: "delete_file"` - - `"concise"` + The operation type. Always `delete_file`. - - `"detailed"` + - `"delete_file"` - - `mode: optional string or "standard" or "pro"` + - `UpdateFile object { diff, path, type }` - Controls the reasoning execution mode for the request. + Instruction for updating an existing file via the apply_patch tool. - When returned on a response, this is the effective execution mode. + - `diff: string` - - `string` + Unified diff content to apply to the existing file. - - `"standard" or "pro"` + - `path: string` - Controls the reasoning execution mode for the request. + Path of the file to update relative to the workspace root. - When returned on a response, this is the effective execution mode. + - `type: "update_file"` - - `"standard"` + The operation type. Always `update_file`. - - `"pro"` + - `"update_file"` - - `summary: optional "auto" or "concise" or "detailed"` + - `status: "in_progress" or "completed"` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + The status of the apply patch tool call. One of `in_progress` or `completed`. - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + - `"in_progress"` - - `"auto"` + - `"completed"` - - `"concise"` + - `type: "apply_patch_call"` - - `"detailed"` + The type of the item. Always `apply_patch_call`. - - `safety_identifier: optional string` + - `"apply_patch_call"` - 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](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `id: optional string` - - `service_tier: optional "auto" or "default" or "flex" or 2 more` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - Specifies the processing type used for serving the request. + - `agent: optional object { agent_name }` - - 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](https://platform.openai.com/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 agent that produced this item. - 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. + - `agent_name: string` - - `"auto"` + The canonical name of the agent that produced this item. - - `"default"` + - `caller: optional object { type } or object { caller_id, type }` - - `"flex"` + The execution context that produced this tool call. - - `"scale"` + - `Direct object { type }` - - `"priority"` + - `type: "direct"` - - `status: optional BetaResponseStatus` + The caller type. Always `direct`. - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + - `"direct"` - - `"completed"` + - `Program object { caller_id, type }` - - `"failed"` + - `caller_id: string` - - `"in_progress"` + The call ID of the program item that produced this tool call. - - `"cancelled"` + - `type: "program"` - - `"queued"` + The caller type. Always `program`. - - `"incomplete"` + - `"program"` - - `text: optional BetaResponseTextConfig` + - `ApplyPatchCallOutput object { call_id, status, type, 4 more }` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + The streamed output emitted by an apply patch tool call. - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `call_id: string` - - `format: optional BetaResponseFormatTextConfig` + The unique ID of the apply patch tool call generated by the model. - An object specifying the format that the model must output. + - `status: "completed" or "failed"` - Configuring `{ "type": "json_schema" }` enables Structured Outputs, - which ensures the model will match your supplied JSON schema. Learn more in the - [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + The status of the apply patch tool call output. One of `completed` or `failed`. - The default format is `{ "type": "text" }` with no additional options. + - `"completed"` - **Not recommended for gpt-4o and newer models:** + - `"failed"` - 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. + - `type: "apply_patch_call_output"` - - `Text object { type }` + The type of the item. Always `apply_patch_call_output`. - Default response format. Used to generate text responses. + - `"apply_patch_call_output"` - - `type: "text"` + - `id: optional string` - The type of response format being defined. Always `text`. + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `"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](https://platform.openai.com/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. + - `caller: optional object { type } or object { caller_id, type }` - - `schema: map[unknown]` + The execution context that produced this 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/). + - `Direct object { type }` - - `type: "json_schema"` + - `type: "direct"` - The type of response format being defined. Always `json_schema`. + The caller type. Always `direct`. - - `"json_schema"` + - `"direct"` - - `description: optional string` + - `Program object { caller_id, type }` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `caller_id: string` - - `strict: optional boolean` + The call ID of the program item that produced this 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](https://platform.openai.com/docs/guides/structured-outputs). + - `type: "program"` - - `JSONObject object { type }` + The caller type. Always `program`. - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + - `"program"` - - `type: "json_object"` + - `output: optional string` - The type of response format being defined. Always `json_object`. + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - - `"json_object"` + - `McpListTools object { id, server_label, tools, 3 more }` - - `verbosity: optional "low" or "medium" or "high"` + A list of tools available on an MCP server. - 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`. + - `id: string` - - `"low"` + The unique ID of the list. - - `"medium"` + - `server_label: string` - - `"high"` + The label of the MCP server. - - `top_logprobs: optional number` + - `tools: array of object { input_schema, name, annotations, description }` - 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 tools available on the server. - - `truncation: optional "auto" or "disabled"` + - `input_schema: unknown` - The truncation strategy to use for the model response. + The JSON schema describing the tool's input. - - `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. + - `name: string` - - `"auto"` + The name of the tool. - - `"disabled"` + - `annotations: optional unknown` - - `usage: optional BetaResponseUsage` + Additional annotations about the tool. - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + - `description: optional string` - - `input_tokens: number` + The description of the tool. - The number of input tokens. + - `type: "mcp_list_tools"` - - `input_tokens_details: object { cache_write_tokens, cached_tokens }` + The type of the item. Always `mcp_list_tools`. - A detailed breakdown of the input tokens. + - `"mcp_list_tools"` - - `cache_write_tokens: number` + - `agent: optional object { agent_name }` - The number of input tokens that were written to the cache. + The agent that produced this item. - - `cached_tokens: number` + - `agent_name: string` - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + The canonical name of the agent that produced this item. - - `output_tokens: number` + - `error: optional string` - The number of output tokens. + Error message if the server could not list tools. - - `output_tokens_details: object { reasoning_tokens }` + - `McpApprovalRequest object { id, arguments, name, 3 more }` - A detailed breakdown of the output tokens. + A request for human approval of a tool invocation. - - `reasoning_tokens: number` + - `id: string` - The number of reasoning tokens. + The unique ID of the approval request. - - `total_tokens: number` + - `arguments: string` - The total number of tokens used. + A JSON string of arguments for the tool. - - `user: optional string` + - `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](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + 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.in_progress"` + - `type: "mcp_approval_request"` - The type of the event. Always `response.in_progress`. + The type of the item. Always `mcp_approval_request`. - - `"response.in_progress"` + - `"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. -### Beta Response Includable + - `McpApprovalResponse object { approval_request_id, approve, type, 3 more }` -- `BetaResponseIncludable = "file_search_call.results" or "web_search_call.results" or "web_search_call.action.sources" or 5 more` + A response to an MCP approval request. - Specify additional output data to include in the model response. Currently supported values are: + - `approval_request_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 approval request being answered. - - `"file_search_call.results"` + - `approve: boolean` - - `"web_search_call.results"` + Whether the request was approved. - - `"web_search_call.action.sources"` + - `type: "mcp_approval_response"` - - `"message.input_image.image_url"` + The type of the item. Always `mcp_approval_response`. - - `"computer_call_output.output.image_url"` + - `"mcp_approval_response"` - - `"code_interpreter_call.outputs"` + - `id: optional string` - - `"reasoning.encrypted_content"` + The unique ID of the approval response - - `"message.output_text.logprobs"` + - `agent: optional object { agent_name }` -### Beta Response Incomplete Event + The agent that produced this item. -- `BetaResponseIncompleteEvent object { response, sequence_number, type, agent }` + - `agent_name: string` - An event that is emitted when a response finishes as incomplete. + The canonical name of the agent that produced this item. - - `response: BetaResponse` + - `reason: optional string` - The response that was incomplete. + Optional reason for the decision. - - `id: string` + - `McpCall object { id, arguments, name, 7 more }` - Unique identifier for this Response. + An invocation of a tool on an MCP server. - - `created_at: number` + - `id: string` - Unix timestamp (in seconds) of when this Response was created. + The unique ID of the tool call. - - `error: BetaResponseError` + - `arguments: string` - An error object returned when the model fails to generate a Response. + A JSON string of the arguments passed to the tool. - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 16 more` + - `name: string` - The error code for the response. + The name of the tool that was run. - - `"server_error"` + - `server_label: string` - - `"rate_limit_exceeded"` + The label of the MCP server running the tool. - - `"invalid_prompt"` + - `type: "mcp_call"` - - `"bio_policy"` + The type of the item. Always `mcp_call`. - - `"vector_store_timeout"` + - `"mcp_call"` - - `"invalid_image"` + - `agent: optional object { agent_name }` - - `"invalid_image_format"` + The agent that produced this item. - - `"invalid_base64_image"` + - `agent_name: string` - - `"invalid_image_url"` + The canonical name of the agent that produced this item. - - `"image_too_large"` + - `approval_request_id: optional string` - - `"image_too_small"` + 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_parse_error"` + - `error: optional string` - - `"image_content_policy_violation"` + The error from the tool call, if any. - - `"invalid_image_mode"` + - `output: optional string` - - `"image_file_too_large"` + The output from the tool call. - - `"unsupported_image_media_type"` + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - - `"empty_image_file"` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `"failed_to_download_image"` + - `"in_progress"` - - `"image_file_not_found"` + - `"completed"` - - `message: string` + - `"incomplete"` - A human-readable description of the error. + - `"calling"` - - `incomplete_details: object { reason }` + - `"failed"` - Details about why the response is incomplete. + - `CustomToolCallOutput object { call_id, output, type, 3 more }` - - `reason: optional "max_output_tokens" or "content_filter"` + The output of a custom tool call from your code, being sent back to the model. - The reason why the response is incomplete. + - `call_id: string` - - `"max_output_tokens"` + The call ID, used to map this custom tool call output to a custom tool call. - - `"content_filter"` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `instructions: string or array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - A system (or developer) message inserted into the model's context. + - `StringOutput = 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. + A string of the output of the custom tool call. - - `string` + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - A text input to the model, equivalent to a text input with the - `developer` role. + Text, image, or file output of the custom tool call. - - `InputItemList = array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - A list of one or many input items to the model, containing - different content types. + A text input to the model. - - `BetaEasyInputMessage object { content, role, phase, type }` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. Messages with the - `assistant` role are presumed to have been generated by the model in previous - interactions. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `content: string or BetaResponseInputMessageContentList` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + A file input to the model. - - `TextInput = string` + - `type: "custom_tool_call_output"` - A text input to the model. + The type of the custom tool call output. Always `custom_tool_call_output`. - - `BetaResponseInputMessageContentList = array of BetaResponseInputContent` + - `"custom_tool_call_output"` - A list of one or many input items to the model, containing different content - types. + - `id: optional string` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + The unique ID of the custom tool call output in the OpenAI platform. - 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"` + The caller type. Always `direct`. - The breakpoint mode. Always `explicit`. + - `"direct"` - - `"explicit"` + - `Program object { caller_id, type }` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `caller_id: string` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The call ID of the program item that produced this tool call. - - `detail: "low" or "high" or "auto" or "original"` + - `type: "program"` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The caller type. Always `program`. - - `"low"` + - `"program"` - - `"high"` + - `CustomToolCall object { call_id, input, name, 5 more }` - - `"auto"` + A call to a custom tool created by the model. - - `"original"` + - `call_id: string` - - `type: "input_image"` + An identifier used to map this custom tool call to a tool call output. - The type of the input item. Always `input_image`. + - `input: string` - - `"input_image"` + The input for the custom tool call generated by the model. - - `file_id: optional string` + - `name: string` - The ID of the file to be sent to the model. + The name of the custom tool being called. - - `image_url: optional string` + - `type: "custom_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. + The type of the custom tool call. Always `custom_tool_call`. - - `prompt_cache_breakpoint: optional object { mode }` + - `"custom_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. + - `id: optional string` - - `mode: "explicit"` + The unique ID of the custom tool call in the OpenAI platform. - 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`. + - `"direct"` - - `"auto"` + - `Program object { caller_id, type }` - - `"low"` + - `caller_id: string` - - `"high"` + The call ID of the program item that produced this tool call. - - `file_data: optional string` + - `type: "program"` - The content of the file to be sent to the model. + - `"program"` - - `file_id: optional string` + - `namespace: optional string` - The ID of the file to be sent to the model. + The namespace of the custom tool being called. - - `file_url: optional string` + - `CompactionTrigger object { type, agent }` - The URL of the file to be sent to the model. + Compacts the current context. Must be the final input item. - - `filename: optional string` + - `type: "compaction_trigger"` - The name of the file to be sent to the model. + The type of the item. Always `compaction_trigger`. - - `prompt_cache_breakpoint: optional object { mode }` + - `"compaction_trigger"` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `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. - - `role: "user" or "assistant" or "system" or "developer"` + - `ItemReference object { id, agent, type }` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + An internal identifier for an item to reference. - - `"user"` + - `id: string` - - `"assistant"` + The ID of the item to reference. - - `"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"` + - `type: optional "item_reference"` - - `"final_answer"` + The type of item to reference. Always `item_reference`. - - `type: optional "message"` + - `"item_reference"` - The type of the message input. Always `message`. + - `Program object { id, call_id, code, 3 more }` - - `"message"` + - `id: string` - - `Message object { content, role, agent, 2 more }` + The unique ID of this program 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. + - `call_id: string` - - `content: BetaResponseInputMessageContentList` + The stable call ID of the program item. - A list of one or many input items to the model, containing different content - types. + - `code: string` - - `role: "user" or "system" or "developer"` + The JavaScript source executed by programmatic tool calling. - The role of the message input. One of `user`, `system`, or `developer`. + - `fingerprint: string` - - `"user"` + Opaque program replay fingerprint that must be round-tripped. - - `"system"` + - `type: "program"` - - `"developer"` + The item type. Always `program`. + + - `"program"` - `agent: optional object { agent_name }` @@ -133679,638 +131785,639 @@ 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"` + - `ProgramOutput object { id, call_id, result, 3 more }` - 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 this program output item. - - `"completed"` + - `call_id: string` - - `"incomplete"` + The call ID of the program item. - - `type: optional "message"` + - `result: string` - The type of the message input. Always set to `message`. + The result produced by the program item. - - `"message"` + - `status: "completed" or "incomplete"` - - `BetaResponseOutputMessage object { id, content, role, 4 more }` + The terminal status of the program output. - An output message from the model. + - `"completed"` - - `id: string` + - `"incomplete"` - The unique ID of the output message. + - `type: "program_output"` - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + The item type. Always `program_output`. - The content of the output message. + - `"program_output"` - - `BetaResponseOutputText object { annotations, text, type, logprobs }` + - `agent: optional object { agent_name }` - A text output from the model. + The agent that produced this 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 }` + - `agent_name: string` - The annotations of the text output. + The canonical name of the agent that produced this item. - - `FileCitation object { file_id, filename, index, type }` + - `response_id: string` - A citation to a file. + The ID of the response that rejected the input. - - `file_id: string` + - `sequence_number: number` - The ID of the file. + The sequence number for this event. - - `filename: string` + - `type: "response.inject.failed"` - The filename of the file cited. + The event discriminator. Always `response.inject.failed`. - - `index: number` + - `"response.inject.failed"` - The index of the file in the list of files. + - `stream_id: optional string` + + The multiplexed WebSocket stream that emitted the event. This field is + present only when WebSocket multiplexing is enabled separately. + +### Beta Response Input Audio + +- `BetaResponseInputAudio object { input_audio, type }` - - `type: "file_citation"` + An audio input to the model. - The type of the file citation. Always `file_citation`. + - `input_audio: object { data, format }` - - `"file_citation"` + - `data: string` - - `URLCitation object { end_index, start_index, title, 2 more }` + Base64-encoded audio data. - A citation for a web resource used to generate a model response. + - `format: "mp3" or "wav"` - - `end_index: number` + The format of the audio data. Currently supported formats are `mp3` and + `wav`. - The index of the last character of the URL citation in the message. + - `"mp3"` - - `start_index: number` + - `"wav"` - The index of the first character of the URL citation in the message. + - `type: "input_audio"` - - `title: string` + The type of the input item. Always `input_audio`. - The title of the web resource. + - `"input_audio"` - - `type: "url_citation"` +### Beta Response Input Content - The type of the URL citation. Always `url_citation`. +- `BetaResponseInputContent = BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `"url_citation"` + A text input to the model. - - `url: string` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - The URL of the web resource. + A text input to the model. - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + - `text: string` - A citation for a container file used to generate a model response. + The text input to the model. - - `container_id: string` + - `type: "input_text"` - The ID of the container file. + The type of the input item. Always `input_text`. - - `end_index: number` + - `"input_text"` - The index of the last character of the container file citation in the message. + - `prompt_cache_breakpoint: optional object { mode }` - - `file_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 ID of the file. + - `mode: "explicit"` - - `filename: string` + The breakpoint mode. Always `explicit`. - The filename of the container file cited. + - `"explicit"` - - `start_index: number` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - The index of the first character of the container file citation in the message. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `type: "container_file_citation"` + - `detail: "low" or "high" or "auto" or "original"` - The type of the container file citation. Always `container_file_citation`. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `"container_file_citation"` + - `"low"` - - `FilePath object { file_id, index, type }` + - `"high"` - A path to a file. + - `"auto"` - - `file_id: string` + - `"original"` - The ID of the file. + - `type: "input_image"` - - `index: number` + The type of the input item. Always `input_image`. - The index of the file in the list of files. + - `"input_image"` - - `type: "file_path"` + - `file_id: optional string` - The type of the file path. Always `file_path`. + The ID of the file to be sent to the model. - - `"file_path"` + - `image_url: optional string` - - `text: 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 text output from the model. + - `prompt_cache_breakpoint: optional object { mode }` - - `type: "output_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. - The type of the output text. Always `output_text`. + - `mode: "explicit"` - - `"output_text"` + The breakpoint mode. Always `explicit`. - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + - `"explicit"` - - `token: string` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `bytes: array of number` + A file input to the model. - - `logprob: number` + - `type: "input_file"` - - `top_logprobs: array of object { token, bytes, logprob }` + The type of the input item. Always `input_file`. - - `token: string` + - `"input_file"` - - `bytes: array of number` + - `detail: optional "auto" or "low" or "high"` - - `logprob: 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`. - - `BetaResponseOutputRefusal object { refusal, type }` + - `"auto"` - A refusal from the model. + - `"low"` - - `refusal: string` + - `"high"` - The refusal explanation from the model. + - `file_data: optional string` - - `type: "refusal"` + The content of the file to be sent to the model. - The type of the refusal. Always `refusal`. + - `file_id: optional string` - - `"refusal"` + The ID of the file to be sent to the model. - - `role: "assistant"` + - `file_url: optional string` - The role of the output message. Always `assistant`. + The URL of the file to be sent to the model. - - `"assistant"` + - `filename: optional string` - - `status: "in_progress" or "completed" or "incomplete"` + The name of the file to be sent to the model. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `prompt_cache_breakpoint: optional object { mode }` - - `"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. - - `"completed"` + - `mode: "explicit"` - - `"incomplete"` + The breakpoint mode. Always `explicit`. - - `type: "message"` + - `"explicit"` - The type of the output message. Always `message`. +### Beta Response Input File - - `"message"` +- `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `agent: optional object { agent_name }` + A file input to the model. - The agent that produced this item. + - `type: "input_file"` - - `agent_name: string` + The type of the input item. Always `input_file`. - The canonical name of the agent that produced this item. + - `"input_file"` - - `phase: optional "commentary" or "final_answer"` + - `detail: optional "auto" or "low" or "high"` - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + 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`. - - `"commentary"` + - `"auto"` - - `"final_answer"` + - `"low"` - - `FileSearchCall object { id, queries, status, 3 more }` + - `"high"` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `file_data: optional string` - - `id: string` + The content of the file to be sent to the model. - The unique ID of the file search tool call. + - `file_id: optional string` - - `queries: array of string` + The ID of the file to be sent to the model. - The queries used to search for files. + - `file_url: optional string` - - `status: "in_progress" or "searching" or "completed" or 2 more` + The URL of the file to be sent to the model. - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `filename: optional string` - - `"in_progress"` + The name of the file to be sent to the model. - - `"searching"` + - `prompt_cache_breakpoint: optional object { mode }` - - `"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. - - `"incomplete"` + - `mode: "explicit"` - - `"failed"` + The breakpoint mode. Always `explicit`. - - `type: "file_search_call"` + - `"explicit"` - The type of the file search tool call. Always `file_search_call`. +### Beta Response Input File Content - - `"file_search_call"` +- `BetaResponseInputFileContent object { type, detail, file_data, 4 more }` - - `agent: optional object { agent_name }` + A file input to the model. - The agent that produced this item. + - `type: "input_file"` - - `agent_name: string` + The type of the input item. Always `input_file`. - The canonical name of the agent that produced this item. + - `"input_file"` - - `results: optional array of object { attributes, file_id, filename, 2 more }` + - `detail: optional "auto" or "low" or "high"` - The results of the file search tool call. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `attributes: optional map[string or number or boolean]` + - `"auto"` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. Keys are strings - with a maximum length of 64 characters. Values are strings with a maximum - length of 512 characters, booleans, or numbers. + - `"low"` - - `string` + - `"high"` - - `number` + - `file_data: optional string` - - `boolean` + The base64-encoded data of the file to be sent to the model. - `file_id: optional string` - The unique ID of the file. + 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. + The name of the file to be sent to the model. - - `score: optional number` + - `prompt_cache_breakpoint: optional object { mode }` - The relevance score of the file - a value between 0 and 1. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `text: optional string` + - `mode: "explicit"` - The text that was retrieved from the file. + The breakpoint mode. Always `explicit`. - - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` + - `"explicit"` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. +### Beta Response Input Image - - `id: string` +- `BetaResponseInputImage object { detail, type, file_id, 2 more }` - The unique ID of the computer call. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `call_id: string` + - `detail: "low" or "high" or "auto" or "original"` - An identifier used when responding to the tool call with output. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `pending_safety_checks: array of object { id, code, message }` + - `"low"` - The pending safety checks for the computer call. + - `"high"` - - `id: string` + - `"auto"` - The ID of the pending safety check. + - `"original"` - - `code: optional string` + - `type: "input_image"` - The type of the pending safety check. + The type of the input item. Always `input_image`. - - `message: optional string` + - `"input_image"` - Details about the pending safety check. + - `file_id: optional string` - - `status: "in_progress" or "completed" or "incomplete"` + The ID of the file to be sent to the model. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `image_url: optional string` - - `"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. - - `"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. - - `type: "computer_call"` + - `mode: "explicit"` - The type of the computer call. Always `computer_call`. + The breakpoint mode. Always `explicit`. - - `"computer_call"` + - `"explicit"` - - `action: optional BetaComputerAction` +### Beta Response Input Image Content - A click action. +- `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` - - `Click object { button, type, x, 2 more }` + An image input to the model. Learn about [image inputs](/docs/guides/vision) - A click action. + - `type: "input_image"` - - `button: "left" or "right" or "wheel" or 2 more` + The type of the input item. Always `input_image`. - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `"input_image"` - - `"left"` + - `detail: optional "low" or "high" or "auto" or "original"` - - `"right"` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `"wheel"` + - `"low"` - - `"back"` + - `"high"` - - `"forward"` + - `"auto"` - - `type: "click"` + - `"original"` - Specifies the event type. For a click action, this property is always `click`. + - `file_id: optional string` - - `"click"` + The ID of the file to be sent to the model. - - `x: number` + - `image_url: optional string` - The x-coordinate where the click occurred. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `y: number` + - `prompt_cache_breakpoint: optional object { mode }` - The y-coordinate where the click occurred. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `keys: optional array of string` + - `mode: "explicit"` - The keys being held while clicking. + The breakpoint mode. Always `explicit`. - - `DoubleClick object { keys, type, x, y }` + - `"explicit"` - A double click action. +### Beta Response Input Message Content List - - `keys: array of string` +- `BetaResponseInputMessageContentList = array of BetaResponseInputContent` - The keys being held while double-clicking. + A list of one or many input items to the model, containing different content + types. - - `type: "double_click"` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - Specifies the event type. For a double click action, this property is always set to `double_click`. + A text input to the model. - - `"double_click"` + - `text: string` - - `x: number` + The text input to the model. - The x-coordinate where the double click occurred. + - `type: "input_text"` - - `y: number` + The type of the input item. Always `input_text`. - The y-coordinate where the double click occurred. + - `"input_text"` - - `Drag object { path, type, keys }` + - `prompt_cache_breakpoint: optional object { mode }` - A drag action. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `path: array of object { x, y }` + - `mode: "explicit"` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + The breakpoint mode. Always `explicit`. - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `"explicit"` - - `x: number` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - The x-coordinate. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `y: number` + - `detail: "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. + - `type: "input_image"` - - `Keypress object { keys, type }` + The type of the input item. Always `input_image`. - A collection of keypresses the model would like to perform. + - `"input_image"` - - `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. + The ID of the file to be sent to the model. - - `type: "keypress"` + - `image_url: optional string` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `"keypress"` + - `prompt_cache_breakpoint: optional object { mode }` - - `Move object { type, x, y, 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 mouse move action. + - `mode: "explicit"` - - `type: "move"` + The breakpoint mode. Always `explicit`. - Specifies the event type. For a move action, this property is always set to `move`. + - `"explicit"` - - `"move"` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `x: number` + A file input to the model. - The x-coordinate to move to. + - `type: "input_file"` - - `y: number` + The type of the input item. Always `input_file`. - The y-coordinate to move to. + - `"input_file"` - - `keys: optional array of string` + - `detail: optional "auto" or "low" or "high"` - The keys being held while moving the mouse. + 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`. - - `Screenshot object { type }` + - `"auto"` - A screenshot action. + - `"low"` - - `type: "screenshot"` + - `"high"` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `file_data: optional string` - - `"screenshot"` + The content of the file to be sent to the model. - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `file_id: optional string` - A scroll action. + The ID of the file to be sent to the model. - - `scroll_x: number` + - `file_url: optional string` - The horizontal scroll distance. + The URL of the file to be sent to the model. - - `scroll_y: number` + - `filename: optional string` - The vertical scroll distance. + The name of the file to be sent to the model. - - `type: "scroll"` + - `prompt_cache_breakpoint: optional object { mode }` - Specifies the event type. For a scroll action, this property is always set to `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. - - `"scroll"` + - `mode: "explicit"` - - `x: number` + The breakpoint mode. Always `explicit`. - The x-coordinate where the scroll occurred. + - `"explicit"` - - `y: number` +### Beta Response Input Message Item - The y-coordinate where the scroll occurred. +- `BetaResponseInputMessageItem object { id, content, role, 3 more }` - - `keys: optional array of string` + - `id: string` - The keys being held while scrolling. + The unique ID of the message input. - - `Type object { text, type }` + - `content: BetaResponseInputMessageContentList` - An action to type in text. + A list of one or many input items to the model, containing different content + types. - - `text: string` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - The text to type. + A text input to the model. - - `type: "type"` + - `text: string` - Specifies the event type. For a type action, this property is always set to `type`. + The text input to the model. - - `"type"` + - `type: "input_text"` - - `Wait object { type }` + The type of the input item. Always `input_text`. - A wait action. + - `"input_text"` - - `type: "wait"` + - `prompt_cache_breakpoint: optional object { mode }` - Specifies the event type. For a wait action, this property is always set to `wait`. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `"wait"` + - `mode: "explicit"` - - `actions: optional BetaComputerActionList` + The breakpoint mode. Always `explicit`. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `"explicit"` - - `Click object { button, type, x, 2 more }` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - A click action. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `DoubleClick object { keys, type, x, y }` + - `detail: "low" or "high" or "auto" or "original"` - A double click action. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `Drag object { path, type, keys }` + - `"low"` - A drag action. + - `"high"` - - `Keypress object { keys, type }` + - `"auto"` - A collection of keypresses the model would like to perform. + - `"original"` - - `Move object { type, x, y, keys }` + - `type: "input_image"` - A mouse move action. + The type of the input item. Always `input_image`. - - `Screenshot object { type }` + - `"input_image"` - A screenshot action. + - `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. + - `image_url: optional string` - - `Type object { text, type }` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - An action to type in text. + - `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"` - - `agent: optional object { agent_name }` + The breakpoint mode. Always `explicit`. - The agent that produced this item. + - `"explicit"` - - `agent_name: string` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - The canonical name of the agent that produced this item. + A file input to the model. - - `ComputerCallOutput object { call_id, output, type, 4 more }` + - `type: "input_file"` - The output of a computer tool call. + The type of the input item. Always `input_file`. - - `call_id: string` + - `"input_file"` - The ID of the computer tool call that produced the output. + - `detail: optional "auto" or "low" or "high"` - - `output: BetaResponseComputerToolCallOutputScreenshot` + 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 computer screenshot image used with the computer use tool. + - `"auto"` - - `type: "computer_screenshot"` + - `"low"` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `"high"` - - `"computer_screenshot"` + - `file_data: optional string` + + The content of the file to be sent to the model. - `file_id: optional string` - The identifier of an uploaded file that contains the screenshot. + The ID of the file to be sent to the model. - - `image_url: optional string` + - `file_url: optional string` - The URL of the screenshot image. + The URL of the file to be sent to the model. - - `type: "computer_call_output"` + - `filename: optional string` - The type of the computer tool call output. Always `computer_call_output`. + The name of the file to be sent to the model. - - `"computer_call_output"` + - `prompt_cache_breakpoint: optional object { mode }` - - `id: optional string` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The ID of the computer tool call output. + - `mode: "explicit"` - - `acknowledged_safety_checks: optional array of object { id, code, message }` + The breakpoint mode. Always `explicit`. - The safety checks reported by the API that have been acknowledged by the developer. + - `"explicit"` - - `id: string` + - `role: "user" or "system" or "developer"` - The ID of the pending safety check. + The role of the message input. One of `user`, `system`, or `developer`. - - `code: optional string` + - `"user"` - The type of the pending safety check. + - `"system"` - - `message: optional string` + - `"developer"` - Details about the pending safety check. + - `type: "message"` + + The type of the message input. Always set to `message`. + + - `"message"` - `agent: optional object { agent_name }` @@ -134322,7 +132429,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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. + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `"in_progress"` @@ -134330,583 +132438,590 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"incomplete"` - - `WebSearchCall object { id, action, status, 2 more }` - - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. +### Beta Response Input Text - - `id: string` +- `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - The unique ID of the web search tool call. + A text input to the model. - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + - `text: 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). + The text input to the model. - - `Search object { type, queries, query, sources }` + - `type: "input_text"` - Action type "search" - Performs a web search query. + The type of the input item. Always `input_text`. - - `type: "search"` + - `"input_text"` - The action type. + - `prompt_cache_breakpoint: optional object { mode }` - - `"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. - - `queries: optional array of string` + - `mode: "explicit"` - The search queries. + The breakpoint mode. Always `explicit`. - - `query: optional string` + - `"explicit"` - The search query. +### Beta Response Input Text Content - - `sources: optional array of object { type, url }` +- `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` - The sources used in the search. + A text input to the model. - - `type: "url"` + - `text: string` - The type of source. Always `url`. + The text input to the model. - - `"url"` + - `type: "input_text"` - - `url: string` + The type of the input item. Always `input_text`. - The URL of the source. + - `"input_text"` - - `OpenPage object { type, url }` + - `prompt_cache_breakpoint: optional object { mode }` - Action type "open_page" - Opens a specific URL from search 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. - - `type: "open_page"` + - `mode: "explicit"` - The action type. + The breakpoint mode. Always `explicit`. - - `"open_page"` + - `"explicit"` - - `url: optional string` +### Beta Response Local Environment - The URL opened by the model. +- `BetaResponseLocalEnvironment object { type }` - - `FindInPage object { pattern, type, url }` + Represents the use of a local environment to perform shell actions. - Action type "find_in_page": Searches for a pattern within a loaded page. + - `type: "local"` - - `pattern: string` + The environment type. Always `local`. - The pattern or text to search for within the page. + - `"local"` - - `type: "find_in_page"` +### Beta Response Mcp Call Arguments Delta Event - The action type. +- `BetaResponseMcpCallArgumentsDeltaEvent object { delta, item_id, output_index, 3 more }` - - `"find_in_page"` + Emitted when there is a delta (partial update) to the arguments of an MCP tool call. - - `url: string` + - `delta: string` - The URL of the page searched for the pattern. + A JSON string containing the partial update to the arguments for the MCP tool call. - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `item_id: string` - The status of the web search tool call. + The unique identifier of the MCP tool call item being processed. - - `"in_progress"` + - `output_index: number` - - `"searching"` + The index of the output item in the response's output array. - - `"completed"` + - `sequence_number: number` - - `"failed"` + The sequence number of this event. - - `type: "web_search_call"` + - `type: "response.mcp_call_arguments.delta"` - The type of the web search tool call. Always `web_search_call`. + The type of the event. Always 'response.mcp_call_arguments.delta'. - - `"web_search_call"` + - `"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. - - `FunctionCall object { arguments, call_id, name, 6 more }` +### Beta Response Mcp Call Arguments Done Event - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. +- `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 of the arguments to pass to the function. + A JSON string containing the finalized arguments for the MCP tool call. - - `call_id: string` + - `item_id: string` - The unique ID of the function tool call generated by the model. + The unique identifier of the MCP tool call item being processed. - - `name: string` + - `output_index: number` - The name of the function to run. + The index of the output item in the response's output array. - - `type: "function_call"` + - `sequence_number: number` - The type of the function tool call. Always `function_call`. + The sequence number of this event. - - `"function_call"` + - `type: "response.mcp_call_arguments.done"` - - `id: optional string` + The type of the event. Always 'response.mcp_call_arguments.done'. - The unique ID of the function tool call. + - `"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. - - `caller: optional object { type } or object { caller_id, type }` +### Beta Response Mcp Call Completed Event - The execution context that produced this tool call. +- `BetaResponseMcpCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` - - `Direct object { type }` + Emitted when an MCP tool call has completed successfully. - - `type: "direct"` + - `item_id: string` - - `"direct"` + The ID of the MCP tool call item that completed. - - `Program object { caller_id, type }` + - `output_index: number` - - `caller_id: string` + The index of the output item that completed. - 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.completed"` - - `namespace: optional string` + The type of the event. Always 'response.mcp_call.completed'. - The namespace of the function to run. + - `"response.mcp_call.completed"` - - `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"` +### Beta Response Mcp Call Failed Event - - `FunctionCallOutput object { call_id, output, type, 4 more }` +- `BetaResponseMcpCallFailedEvent object { item_id, output_index, sequence_number, 2 more }` - The output of a function tool call. + Emitted when an MCP tool call has failed. - - `call_id: string` + - `item_id: string` - The unique ID of the function tool call generated by the model. + The ID of the MCP tool call item that failed. - - `output: string or BetaResponseFunctionCallOutputItemList` + - `output_index: number` - Text, image, or file output of the function tool call. + The index of the output item that failed. - - `string` + - `sequence_number: number` - A JSON string of the output of the function tool call. + The sequence number of this event. - - `BetaResponseFunctionCallOutputItemList = array of BetaResponseFunctionCallOutputItem` + - `type: "response.mcp_call.failed"` - An array of content outputs (text, image, file) for the function tool call. + The type of the event. Always 'response.mcp_call.failed'. - - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` + - `"response.mcp_call.failed"` - 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 Mcp Call In Progress Event - - `"input_text"` +- `BetaResponseMcpCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` - - `prompt_cache_breakpoint: optional object { mode }` + Emitted when an MCP tool call is 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. + - `item_id: string` - - `mode: "explicit"` + The unique identifier of the MCP tool call item being processed. - The breakpoint mode. Always `explicit`. + - `output_index: number` - - `"explicit"` + The index of the output item in the response's output array. - - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` + - `sequence_number: number` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + The sequence number of this event. - - `type: "input_image"` + - `type: "response.mcp_call.in_progress"` - The type of the input item. Always `input_image`. + The type of the event. Always 'response.mcp_call.in_progress'. - - `"input_image"` + - `"response.mcp_call.in_progress"` - - `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 owns this multi-agent streaming event. - - `"low"` + - `agent_name: string` - - `"high"` + The canonical name of the agent that produced this item. - - `"auto"` +### Beta Response Mcp List Tools Completed Event - - `"original"` +- `BetaResponseMcpListToolsCompletedEvent object { item_id, output_index, sequence_number, 2 more }` - - `file_id: optional string` + Emitted when the list of available MCP tools has been successfully retrieved. - The ID of the file to be sent to the model. + - `item_id: string` - - `image_url: optional string` + The ID of the MCP tool call item that produced this output. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `output_index: number` - - `prompt_cache_breakpoint: optional object { mode }` + The index of the output item that was processed. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `sequence_number: number` - - `mode: "explicit"` + The sequence number of this event. - The breakpoint mode. Always `explicit`. + - `type: "response.mcp_list_tools.completed"` - - `"explicit"` + The type of the event. Always 'response.mcp_list_tools.completed'. - - `BetaResponseInputFileContent object { type, detail, file_data, 4 more }` + - `"response.mcp_list_tools.completed"` - A file input to the model. + - `agent: optional object { agent_name }` - - `type: "input_file"` + The agent that owns this multi-agent streaming event. - 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"` +### Beta Response Mcp List Tools Failed Event - 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`. +- `BetaResponseMcpListToolsFailedEvent object { item_id, output_index, sequence_number, 2 more }` - - `"auto"` + Emitted when the attempt to list available MCP tools has failed. - - `"low"` + - `item_id: string` - - `"high"` + The ID of the MCP tool call item that failed. - - `file_data: optional string` + - `output_index: number` - The base64-encoded data of the file to be sent to the model. + The index of the output item that failed. - - `file_id: optional string` + - `sequence_number: number` - The ID of the file to be sent to the model. + The sequence number of this event. - - `file_url: optional string` + - `type: "response.mcp_list_tools.failed"` - The URL of the file to be sent to the model. + The type of the event. Always 'response.mcp_list_tools.failed'. - - `filename: optional string` + - `"response.mcp_list_tools.failed"` - 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 owns this multi-agent streaming event. - Marks the exact end of a reusable 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`. +### Beta Response Mcp List Tools In Progress Event - - `"explicit"` +- `BetaResponseMcpListToolsInProgressEvent object { item_id, output_index, sequence_number, 2 more }` - - `type: "function_call_output"` + Emitted when the system is in the process of retrieving the list of available MCP tools. - The type of the function tool call output. Always `function_call_output`. + - `item_id: string` - - `"function_call_output"` + The ID of the MCP tool call item that is being processed. - - `id: optional string` + - `output_index: number` - The unique ID of the function tool call output. Populated when this item is returned via API. + The index of the output item that is being processed. + + - `sequence_number: number` + + The sequence number of this event. + + - `type: "response.mcp_list_tools.in_progress"` + + The type of the event. Always 'response.mcp_list_tools.in_progress'. + + - `"response.mcp_list_tools.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 }` - - The execution context that produced this tool call. +### Beta Response Output Audio - - `Direct object { type }` +- `BetaResponseOutputAudio object { data, transcript, type }` - - `type: "direct"` + An audio output from the model. - The caller type. Always `direct`. + - `data: string` - - `"direct"` + Base64-encoded audio data from the model. - - `Program object { caller_id, type }` + - `transcript: string` - - `caller_id: string` + The transcript of the audio data from the model. - The call ID of the program item that produced this tool call. + - `type: "output_audio"` - - `type: "program"` + The type of the output audio. Always `output_audio`. - The caller type. Always `program`. + - `"output_audio"` - - `"program"` +### Beta Response Output Item - - `status: optional "in_progress" or "completed" or "incomplete"` +- `BetaResponseOutputItem = BetaResponseOutputMessage or object { id, queries, status, 3 more } or object { arguments, call_id, name, 6 more } or 28 more` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + An output message from the model. - - `"in_progress"` + - `BetaResponseOutputMessage object { id, content, role, 4 more }` - - `"completed"` + An output message from the model. - - `"incomplete"` + - `id: string` - - `AgentMessage object { author, content, recipient, 3 more }` + The unique ID of the output message. - A message routed between agents. + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - - `author: string` + The content of the output message. - The sending agent identity. + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` + A text output from the model. - Plaintext, image, or encrypted content sent between agents. + - `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 }` - - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` + The annotations of the text output. - A text input to the model. + - `FileCitation object { file_id, filename, index, type }` - - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` + A citation to a file. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `file_id: string` - - `EncryptedContent object { encrypted_content, type }` + The ID of the file. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `filename: string` - - `encrypted_content: string` + The filename of the file cited. - Opaque encrypted content. + - `index: number` - - `type: "encrypted_content"` + The index of the file in the list of files. - The type of the input item. Always `encrypted_content`. + - `type: "file_citation"` - - `"encrypted_content"` + The type of the file citation. Always `file_citation`. - - `recipient: string` + - `"file_citation"` - The destination agent identity. + - `URLCitation object { end_index, start_index, title, 2 more }` - - `type: "agent_message"` + A citation for a web resource used to generate a model response. - The item type. Always `agent_message`. + - `end_index: number` - - `"agent_message"` + The index of the last character of the URL citation in the message. - - `id: optional string` + - `start_index: number` - The unique ID of this agent message item. + 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`. - - `MultiAgentCall object { action, arguments, call_id, 3 more }` + - `"url_citation"` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `url: string` - The multi-agent action that was executed. + The URL of the web resource. - - `"spawn_agent"` + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - - `"interrupt_agent"` + A citation for a container file used to generate a model response. - - `"list_agents"` + - `container_id: string` - - `"send_message"` + The ID of the container file. - - `"followup_task"` + - `end_index: number` - - `"wait_agent"` + The index of the last character of the container file citation in the message. - - `arguments: string` + - `file_id: string` - The action arguments as a JSON string. + The ID of the file. - - `call_id: string` + - `filename: string` - The unique ID linking this call to its output. + The filename of the container file cited. - - `type: "multi_agent_call"` + - `start_index: number` - The item type. Always `multi_agent_call`. + The index of the first character of the container file citation in the message. - - `"multi_agent_call"` + - `type: "container_file_citation"` - - `id: optional string` + The type of the container file citation. Always `container_file_citation`. - The unique ID of this multi-agent call. + - `"container_file_citation"` - - `agent: optional object { agent_name }` + - `FilePath object { file_id, index, type }` - The agent that produced this item. + A path to a file. - - `agent_name: string` + - `file_id: string` - The canonical name of the agent that produced this item. + The ID of the file. - - `MultiAgentCallOutput object { action, call_id, output, 3 more }` + - `index: number` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + The index of the file in the list of files. - The multi-agent action that produced this result. + - `type: "file_path"` - - `"spawn_agent"` + The type of the file path. Always `file_path`. - - `"interrupt_agent"` + - `"file_path"` - - `"list_agents"` + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - - `"send_message"` + - `token: string` - - `"followup_task"` + - `bytes: array of number` - - `"wait_agent"` + - `logprob: number` - - `call_id: string` + - `top_logprobs: array of object { token, bytes, logprob }` - The unique ID of the multi-agent call. + - `token: string` - - `output: array of object { text, type, annotations }` + - `bytes: array of number` - Text output returned by the multi-agent action. + - `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 array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` - - Citations associated with the text content. + - `BetaResponseOutputRefusal object { refusal, type }` - - `array of 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"` - - `array of 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"` - - `array of 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 }` @@ -134916,1223 +133031,1187 @@ 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 }` - - - `arguments: unknown` - - The arguments supplied to the tool search call. - - - `type: "tool_search_call"` + - `results: optional array of object { attributes, file_id, filename, 2 more }` - The item type. Always `tool_search_call`. + The results of the file search tool call. - - `"tool_search_call"` + - `attributes: optional map[string or number or boolean]` - - `id: 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 unique ID of this tool search call. + - `string` - - `agent: optional object { agent_name }` + - `number` - The agent that produced this item. + - `boolean` - - `agent_name: string` + - `file_id: optional string` - The canonical name of the agent that produced this item. + The unique ID of the file. - - `call_id: optional string` + - `filename: optional string` - The unique ID of the tool search call generated by the model. + The name of the file. - - `execution: optional "server" or "client"` + - `score: optional number` - Whether tool search was executed by the server or by the client. + The relevance score of the file - a value between 0 and 1. - - `"server"` + - `text: optional string` - - `"client"` + The text that was retrieved from the file. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `FunctionCall object { arguments, call_id, name, 6 more }` - The status of the tool search call. + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. - - `"in_progress"` + - `arguments: string` - - `"completed"` + A JSON string of the arguments to pass to the function. - - `"incomplete"` + - `call_id: string` - - `ToolSearchOutput object { tools, type, id, 4 more }` + The unique ID of the function tool call generated 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` + - `name: string` - The loaded tool definitions returned by the tool search output. + The name of the function to run. - - `Function object { name, parameters, strict, 5 more }` + - `type: "function_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). + The type of the function tool call. Always `function_call`. - - `name: string` + - `"function_call"` - The name of the function to call. + - `id: optional string` - - `parameters: map[unknown]` + The unique ID of the function tool call. - A JSON schema object describing the parameters of the function. + - `agent: optional object { agent_name }` - - `strict: boolean` + The agent that produced this item. - 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`. + - `caller: optional object { type } or object { caller_id, type }` - - `"function"` + 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"` - - - `defer_loading: optional boolean` + - `Program object { caller_id, type }` - Whether this function is deferred and loaded via tool search. + - `caller_id: string` - - `description: optional string` + The call ID of the program item that produced this tool call. - A description of the function. Used by the model to determine whether or not to call the function. + - `type: "program"` - - `output_schema: optional map[unknown]` + - `"program"` - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `namespace: optional string` - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + The namespace of the function to run. - 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). + - `status: optional "in_progress" or "completed" or "incomplete"` - - `type: "file_search"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The type of the file search tool. Always `file_search`. + - `"in_progress"` - - `"file_search"` + - `"completed"` - - `vector_store_ids: array of string` + - `"incomplete"` - The IDs of the vector stores to search. + - `FunctionCallOutput object { id, call_id, output, 5 more }` - - `filters: optional object { key, type, value } or object { filters, type }` + - `id: string` - A filter to apply. + The unique ID of the function call tool output. - - `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 function tool call generated by the model. - - `key: string` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - The key to compare against the value. + The output from the function call generated by your code. + Can be a string or an list of output content. - - `type: "eq" or "ne" or "gt" or 5 more` + - `StringOutput = string` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + A string of the output of the function 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 + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `"eq"` + Text, image, or file output of the function call. - - `"ne"` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `"gt"` + A text input to the model. - - `"gte"` + - `text: string` - - `"lt"` + The text input to the model. - - `"lte"` + - `type: "input_text"` - - `"in"` + The type of the input item. Always `input_text`. - - `"nin"` + - `"input_text"` - - `value: string or number or boolean or array of string or number` + - `prompt_cache_breakpoint: optional object { mode }` - The value to compare against the attribute key; supports string, number, or boolean types. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `string` + - `mode: "explicit"` - - `number` + The breakpoint mode. Always `explicit`. - - `boolean` + - `"explicit"` - - `array of string or number` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `string` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `number` + - `detail: "low" or "high" or "auto" or "original"` - - `CompoundFilter object { filters, type }` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - Combine multiple filters using `and` or `or`. + - `"low"` - - `filters: array of object { key, type, value } or unknown` + - `"high"` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `"auto"` - - `ComparisonFilter object { key, type, value }` + - `"original"` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `type: "input_image"` - - `key: string` + The type of the input item. Always `input_image`. - The key to compare against the value. + - `"input_image"` - - `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 + - `image_url: optional string` - - `"eq"` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `"ne"` + - `prompt_cache_breakpoint: optional object { mode }` - - `"gt"` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `"gte"` + - `mode: "explicit"` - - `"lt"` + The breakpoint mode. Always `explicit`. - - `"lte"` + - `"explicit"` - - `"in"` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `"nin"` + A file input to the model. - - `value: string or number or boolean or array of string or number` + - `type: "input_file"` - The value to compare against the attribute key; supports string, number, or boolean types. + The type of the input item. Always `input_file`. - - `string` + - `"input_file"` - - `number` + - `detail: optional "auto" or "low" or "high"` - - `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`. - - `array of string or number` + - `"auto"` - - `string` + - `"low"` - - `number` + - `"high"` - - `unknown` + - `file_data: optional string` - - `type: "and" or "or"` + The content of the file to be sent to the model. - Type of operation: `and` or `or`. + - `file_id: optional string` - - `"and"` + The ID of the file to be sent to the model. - - `"or"` + - `file_url: optional string` - - `max_num_results: optional number` + The URL of the file to be sent to the model. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `filename: optional string` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + The name of the file to be sent to the model. - 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` + - `status: "in_progress" or "completed" or "incomplete"` - The weight of the text in the reciprocal ranking fusion. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `ranker: optional "auto" or "default-2024-11-15"` + - `"in_progress"` - The ranker to use for the file search. + - `"completed"` - - `"auto"` + - `"incomplete"` - - `"default-2024-11-15"` + - `type: "function_call_output"` - - `score_threshold: optional number` + The type of the function tool call output. Always `function_call_output`. - 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. + - `"function_call_output"` - - `Computer object { 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. - - `type: "computer"` + - `agent_name: string` - The type of the computer tool. Always `computer`. + The canonical name of the agent that produced this item. - - `"computer"` + - `caller: optional object { type } or object { caller_id, type }` - - `ComputerUsePreview object { display_height, display_width, environment, type }` + The execution context 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). + - `Direct object { type }` - - `display_height: number` + - `type: "direct"` - The height of the computer display. + The caller type. Always `direct`. - - `display_width: number` + - `"direct"` - The width of the computer display. + - `Program object { caller_id, type }` - - `environment: "windows" or "mac" or "linux" or 2 more` + - `caller_id: string` - The type of computer environment to control. + The call ID of the program item that produced this tool call. - - `"windows"` + - `type: "program"` - - `"mac"` + The caller type. Always `program`. - - `"linux"` + - `"program"` - - `"ubuntu"` + - `created_by: optional string` - - `"browser"` + The identifier of the actor that created the item. - - `type: "computer_use_preview"` + - `AgentMessage object { id, author, content, 3 more }` - The type of the computer use tool. Always `computer_use_preview`. + - `id: string` - - `"computer_use_preview"` + The unique ID of the agent message. - - `WebSearch object { type, filters, search_context_size, user_location }` + - `author: string` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The sending agent identity. - - `type: "web_search" or "web_search_2025_08_26"` + - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + Encrypted content sent between agents. - - `"web_search"` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `"web_search_2025_08_26"` + A text input to the model. - - `filters: optional object { allowed_domains }` + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - Filters for the search. + A text output from the model. - - `allowed_domains: optional array of string` + - `Text object { text, type }` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + A text content. - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `text: string` - - `search_context_size: optional "low" or "medium" or "high"` + - `type: "text"` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `"text"` - - `"low"` + - `SummaryText object { text, type }` - - `"medium"` + A summary text from the model. - - `"high"` + - `text: string` - - `user_location: optional object { city, country, region, 2 more }` + A summary of the reasoning output from the model so far. - The approximate location of the user. + - `type: "summary_text"` - - `city: optional string` + The type of the object. Always `summary_text`. - Free text input for the city of the user, e.g. `San Francisco`. + - `"summary_text"` - - `country: optional string` + - `ReasoningText object { text, type }` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + Reasoning text from the model. - - `region: optional string` + - `text: string` - Free text input for the region of the user, e.g. `California`. + The reasoning text from the model. - - `timezone: optional string` + - `type: "reasoning_text"` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The type of the reasoning text. Always `reasoning_text`. - - `type: optional "approximate"` + - `"reasoning_text"` - The type of location approximation. Always `approximate`. + - `BetaResponseOutputRefusal object { refusal, type }` - - `"approximate"` + A refusal from the model. - - `Mcp object { server_label, type, allowed_callers, 9 more }` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `server_label: string` + - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` - A label for this MCP server, used to identify it in tool calls. + A screenshot of a computer. - - `type: "mcp"` + - `detail: "low" or "high" or "auto" or "original"` - The type of the MCP tool. Always `mcp`. + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `"mcp"` + - `"low"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"high"` - The tool invocation context(s). + - `"auto"` - - `"direct"` + - `"original"` - - `"programmatic"` + - `file_id: string` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + The identifier of an uploaded file that contains the screenshot. - List of allowed tool names or a filter object. + - `image_url: string` - - `McpAllowedTools = array of string` + The URL of the screenshot image. - A string array of allowed tool names + - `type: "computer_screenshot"` - - `McpToolFilter object { read_only, tool_names }` + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - A filter object to specify which tools are allowed. + - `"computer_screenshot"` - - `read_only: optional boolean` + - `prompt_cache_breakpoint: optional object { mode }` - 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. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `tool_names: optional array of string` + - `mode: "explicit"` - List of allowed tool names. + The breakpoint mode. Always `explicit`. - - `authorization: optional string` + - `"explicit"` - 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. + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + A file input to the model. - 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + - `EncryptedContent object { encrypted_content, type }` - Currently supported `connector_id` values are: + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - 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` + - `encrypted_content: string` - - `"connector_dropbox"` + Opaque encrypted content. - - `"connector_gmail"` + - `type: "encrypted_content"` - - `"connector_googlecalendar"` + The type of the input item. Always `encrypted_content`. - - `"connector_googledrive"` + - `"encrypted_content"` - - `"connector_microsoftteams"` + - `recipient: string` - - `"connector_outlookcalendar"` + The destination agent identity. - - `"connector_outlookemail"` + - `type: "agent_message"` - - `"connector_sharepoint"` + The type of the item. Always `agent_message`. - - `defer_loading: optional boolean` + - `"agent_message"` - 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. + - `MultiAgentCall object { id, action, arguments, 3 more }` - - `McpToolApprovalFilter object { always, never }` + - `id: string` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + The unique ID of the multi-agent call item. - - `always: optional object { read_only, tool_names }` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - A filter object to specify which tools are allowed. + The multi-agent action to execute. - - `read_only: optional boolean` + - `"spawn_agent"` - 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. + - `"interrupt_agent"` - - `tool_names: optional array of string` + - `"list_agents"` - List of allowed tool names. + - `"send_message"` - - `never: optional object { read_only, tool_names }` + - `"followup_task"` - A filter object to specify which tools are allowed. + - `"wait_agent"` - - `read_only: optional boolean` + - `arguments: 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 JSON string of arguments generated for the action. - - `tool_names: optional array of string` + - `call_id: string` - List of allowed tool names. + The unique ID linking this call to its output. - - `McpToolApprovalSetting = "always" or "never"` + - `type: "multi_agent_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 multi-agent call. Always `multi_agent_call`. - - `"always"` + - `"multi_agent_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. + - `MultiAgentCallOutput object { id, action, call_id, 3 more }` - - `tunnel_id: optional string` + - `id: 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 unique ID of the multi-agent call output item. - - `CodeInterpreter object { container, type, allowed_callers }` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - A tool that runs Python code to help generate a response to a prompt. + The multi-agent action that produced this result. - - `container: string or object { type, file_ids, memory_limit, network_policy }` + - `"spawn_agent"` - 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. + - `"interrupt_agent"` - - `string` + - `"list_agents"` - The container ID. + - `"send_message"` - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + - `"followup_task"` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `"wait_agent"` - - `type: "auto"` + - `call_id: string` - Always `auto`. + The unique ID of the multi-agent call. - - `"auto"` + - `output: array of BetaResponseOutputText` - - `file_ids: optional array of string` + Text output returned by the multi-agent action. - An optional list of uploaded files to make available to your code. + - `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 }` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + The annotations of the text output. - The memory limit for the code interpreter container. + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - - `"1g"` + - `text: string` - - `"4g"` + The text output from the model. - - `"16g"` + - `type: "output_text"` - - `"64g"` + The type of the output text. Always `output_text`. - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `type: "multi_agent_call_output"` - Network access policy for the container. + The type of the multi-agent result. Always `multi_agent_call_output`. - - `BetaContainerNetworkPolicyDisabled object { type }` + - `"multi_agent_call_output"` - - `type: "disabled"` + - `agent: optional object { agent_name }` - Disable outbound network access. Always `disabled`. + The agent that produced this item. - - `"disabled"` + - `agent_name: string` - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + The canonical name of the agent that produced this item. - - `allowed_domains: array of string` + - `WebSearchCall object { id, action, status, 2 more }` - A list of allowed domains when type is `allowlist`. + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. - - `type: "allowlist"` + - `id: string` - Allow outbound network access only to specified domains. Always `allowlist`. + The unique ID of the web search tool call. - - `"allowlist"` + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` + 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). - Optional domain-scoped secrets for allowlisted domains. + - `Search object { type, queries, query, sources }` - - `domain: string` + Action type "search" - Performs a web search query. - The domain associated with the secret. + - `type: "search"` - - `name: string` + The action type. - The name of the secret to inject for the domain. + - `"search"` - - `value: string` + - `queries: optional array of string` - The secret value to inject for the domain. + The search queries. - - `type: "code_interpreter"` + - `query: optional string` - The type of the code interpreter tool. Always `code_interpreter`. + The search query. - - `"code_interpreter"` + - `sources: optional array of object { type, url }` - - `allowed_callers: optional array of "direct" or "programmatic"` + The sources used in the search. - The tool invocation context(s). + - `type: "url"` - - `"direct"` + The type of source. Always `url`. - - `"programmatic"` + - `"url"` - - `ProgrammaticToolCalling object { type }` + - `url: string` - - `type: "programmatic_tool_calling"` + The URL of the source. - The type of the tool. Always `programmatic_tool_calling`. + - `OpenPage object { type, url }` - - `"programmatic_tool_calling"` + Action type "open_page" - Opens a specific URL from search results. - - `ImageGeneration object { type, action, background, 9 more }` + - `type: "open_page"` - A tool that generates images using the GPT image models. + The action type. - - `type: "image_generation"` + - `"open_page"` - The type of the image generation tool. Always `image_generation`. + - `url: optional string` - - `"image_generation"` + The URL opened by the model. - - `action: optional "generate" or "edit" or "auto"` + - `FindInPage object { pattern, type, url }` - Whether to generate a new image or edit an existing image. Default: `auto`. + Action type "find_in_page": Searches for a pattern within a loaded page. - - `"generate"` + - `pattern: string` - - `"edit"` + The pattern or text to search for within the page. - - `"auto"` + - `type: "find_in_page"` - - `background: optional "transparent" or "opaque" or "auto"` + The action type. - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + - `"find_in_page"` - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + - `url: string` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + The URL of the page searched for the pattern. - - `"transparent"` + - `status: "in_progress" or "searching" or "completed" or "failed"` - - `"opaque"` + The status of the web search tool call. - - `"auto"` + - `"in_progress"` - - `input_fidelity: optional "high" or "low"` + - `"searching"` - 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"` + - `"failed"` - - `"low"` + - `type: "web_search_call"` - - `input_image_mask: optional object { file_id, image_url }` + The type of the web search tool call. Always `web_search_call`. - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `"web_search_call"` - - `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-2" or 3 more` + - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` - The image generation model to use. Default: `gpt-image-1`. + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - - `string` + - `id: string` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + The unique ID of the computer call. - The image generation model to use. Default: `gpt-image-1`. + - `call_id: string` - - `"gpt-image-1"` + An identifier used when responding to the tool call with output. - - `"gpt-image-1-mini"` + - `pending_safety_checks: array of object { id, code, message }` - - `"gpt-image-2"` + The pending safety checks for the computer call. - - `"gpt-image-2-2026-04-21"` + - `id: string` - - `"gpt-image-1.5"` + The ID of the pending safety check. - - `"chatgpt-image-latest"` + - `code: optional string` - - `moderation: optional "auto" or "low"` + The type of the pending safety check. - Moderation level for the generated image. Default: `auto`. + - `message: optional string` - - `"auto"` + Details about the pending safety check. - - `"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: "computer_call"` - - `"webp"` + The type of the computer call. Always `computer_call`. - - `"jpeg"` + - `"computer_call"` - - `partial_images: optional number` + - `action: optional BetaComputerAction` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + A click action. - - `quality: optional "low" or "medium" or "high" or "auto"` + - `Click object { button, type, x, 2 more }` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + A click action. - - `"low"` + - `button: "left" or "right" or "wheel" or 2 more` - - `"medium"` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `"high"` + - `"left"` - - `"auto"` + - `"right"` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `"wheel"` - 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`. + - `"back"` - - `string` + - `"forward"` - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `type: "click"` - 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 event type. For a click action, this property is always `click`. - - `"1024x1024"` + - `"click"` - - `"1024x1536"` + - `x: number` - - `"1536x1024"` + The x-coordinate where the click occurred. - - `"auto"` + - `y: number` - - `LocalShell object { type }` + The y-coordinate where the click occurred. - A tool that allows the model to execute shell commands in a local environment. + - `keys: optional array of string` - - `type: "local_shell"` + The keys being held while clicking. - The type of the local shell tool. Always `local_shell`. + - `DoubleClick object { keys, type, x, y }` - - `"local_shell"` + A double click action. - - `Shell object { type, allowed_callers, environment }` + - `keys: array of string` - A tool that allows the model to execute shell commands. + The keys being held while double-clicking. - - `type: "shell"` + - `type: "double_click"` - The type of the shell tool. Always `shell`. + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `"shell"` + - `"double_click"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `x: number` - The tool invocation context(s). + The x-coordinate where the double click occurred. - - `"direct"` + - `y: number` - - `"programmatic"` + The y-coordinate where the double click occurred. - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + - `Drag object { path, type, keys }` - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + A drag action. - - `type: "container_auto"` + - `path: array of object { x, y }` - Automatically creates a container for this request + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `"container_auto"` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `file_ids: optional array of string` + - `x: number` - An optional list of uploaded files to make available to your code. + The x-coordinate. - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `y: number` - The memory limit for the container. + The y-coordinate. - - `"1g"` + - `type: "drag"` - - `"4g"` + Specifies the event type. For a drag action, this property is always set to `drag`. - - `"16g"` + - `"drag"` - - `"64g"` + - `keys: optional array of string` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + The keys being held while dragging the mouse. - Network access policy for the container. + - `Keypress object { keys, type }` - - `BetaContainerNetworkPolicyDisabled object { type }` + A collection of keypresses the model would like to perform. - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `keys: array of string` - - `skills: optional array of BetaSkillReference or BetaInlineSkill` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - An optional list of skills referenced by id or inline data. + - `type: "keypress"` - - `BetaSkillReference object { skill_id, type, version }` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `skill_id: string` + - `"keypress"` - The ID of the referenced skill. + - `Move object { type, x, y, keys }` - - `type: "skill_reference"` + A mouse move action. - References a skill created with the /v1/skills endpoint. + - `type: "move"` - - `"skill_reference"` + Specifies the event type. For a move action, this property is always set to `move`. - - `version: optional string` + - `"move"` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `x: number` - - `BetaInlineSkill object { description, name, source, type }` + The x-coordinate to move to. - - `description: string` + - `y: number` - The description of the skill. + The y-coordinate to move to. - - `name: string` + - `keys: optional array of string` - The name of the skill. + The keys being held while moving the mouse. - - `source: BetaInlineSkillSource` + - `Screenshot object { type }` - Inline skill payload + A screenshot action. - - `data: string` + - `type: "screenshot"` - Base64-encoded skill zip bundle. + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `media_type: "application/zip"` + - `"screenshot"` - The media type of the inline skill payload. Must be `application/zip`. + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - - `"application/zip"` + A scroll action. - - `type: "base64"` + - `scroll_x: number` - The type of the inline skill source. Must be `base64`. + The horizontal scroll distance. - - `"base64"` + - `scroll_y: number` - - `type: "inline"` + The vertical scroll distance. - Defines an inline skill for this request. + - `type: "scroll"` - - `"inline"` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `BetaLocalEnvironment object { type, skills }` + - `"scroll"` - - `type: "local"` + - `x: number` - Use a local computer environment. + The x-coordinate where the scroll occurred. - - `"local"` + - `y: number` - - `skills: optional array of BetaLocalSkill` + The y-coordinate where the scroll occurred. - An optional list of skills. + - `keys: optional array of string` - - `description: string` + The keys being held while scrolling. - The description of the skill. + - `Type object { text, type }` - - `name: string` + An action to type in text. - The name of the skill. + - `text: string` - - `path: string` + The text to type. - The path to the directory containing the skill. + - `type: "type"` - - `BetaContainerReference object { container_id, type }` + Specifies the event type. For a type action, this property is always set to `type`. - - `container_id: string` + - `"type"` - The ID of the referenced container. + - `Wait object { type }` - - `type: "container_reference"` + A wait action. - References a container created with the /v1/containers endpoint + - `type: "wait"` - - `"container_reference"` + Specifies the event type. For a wait action, this property is always set to `wait`. - - `Custom object { name, type, allowed_callers, 3 more }` + - `"wait"` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `actions: optional BetaComputerActionList` - - `name: string` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - The name of the custom tool, used to identify it in tool calls. + - `Click object { button, type, x, 2 more }` - - `type: "custom"` + A click action. - The type of the custom tool. Always `custom`. + - `DoubleClick object { keys, type, x, y }` - - `"custom"` + A double click action. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `Drag object { path, type, keys }` - The tool invocation context(s). + A drag action. - - `"direct"` + - `Keypress object { keys, type }` - - `"programmatic"` + A collection of keypresses the model would like to perform. - - `defer_loading: optional boolean` + - `Move object { type, x, y, keys }` - Whether this tool should be deferred and discovered via tool search. + A mouse move action. - - `description: optional string` + - `Screenshot object { type }` - Optional description of the custom tool, used to provide more context. + A screenshot action. - - `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 }` + - `Type object { text, type }` - Unconstrained free-form text. + An action to type in text. - - `type: "text"` + - `Wait object { type }` - Unconstrained text format. Always `text`. + A wait action. - - `"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. + - `ComputerCallOutput object { id, call_id, output, 5 more }` - - `syntax: "lark" or "regex"` + - `id: string` - The syntax of the grammar definition. One of `lark` or `regex`. + The unique ID of the computer call tool output. - - `"lark"` + - `call_id: string` - - `"regex"` + The ID of the computer tool call that produced the output. - - `type: "grammar"` + - `output: BetaResponseComputerToolCallOutputScreenshot` - Grammar format. Always `grammar`. + A computer screenshot image used with the computer use tool. - - `"grammar"` + - `type: "computer_screenshot"` - - `Namespace object { description, name, tools, type }` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - Groups function/custom tools under a shared namespace. + - `"computer_screenshot"` - - `description: string` + - `file_id: optional string` - A description of the namespace shown to the model. + The identifier of an uploaded file that contains the screenshot. - - `name: string` + - `image_url: optional string` - The namespace name used in tool calls (for example, `crm`). + The URL of the screenshot image. - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + - `status: "completed" or "incomplete" or "failed" or "in_progress"` - The function/custom tools available inside this namespace. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `Function object { name, type, allowed_callers, 5 more }` + - `"completed"` - - `name: string` + - `"incomplete"` - - `type: "function"` + - `"failed"` - - `"function"` + - `"in_progress"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `type: "computer_call_output"` - The tool invocation context(s). + The type of the computer tool call output. Always `computer_call_output`. - - `"direct"` + - `"computer_call_output"` - - `"programmatic"` + - `acknowledged_safety_checks: optional array of object { id, code, message }` - - `defer_loading: optional boolean` + The safety checks reported by the API that have been acknowledged by the + developer. - Whether this function should be deferred and discovered via tool search. + - `id: string` - - `description: optional string` + The ID of the pending safety check. - - `output_schema: optional map[unknown]` + - `code: 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 type of the pending safety check. - - `parameters: optional unknown` + - `message: optional string` - - `strict: optional boolean` + Details about the pending safety check. - 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: optional object { agent_name }` - - `Custom object { name, type, allowed_callers, 3 more }` + The agent that produced this item. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `agent_name: string` - - `name: string` + The canonical name of the agent that produced this item. - The name of the custom tool, used to identify it in tool calls. + - `created_by: optional string` - - `type: "custom"` + The identifier of the actor that created the item. - The type of the custom tool. Always `custom`. + - `Reasoning object { id, summary, type, 4 more }` - - `"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). - - `allowed_callers: optional array of "direct" or "programmatic"` + - `id: string` - The tool invocation context(s). + The unique identifier of the reasoning content. - - `"direct"` + - `summary: array of object { text, type }` - - `"programmatic"` + Reasoning summary content. - - `defer_loading: optional boolean` + - `text: string` - Whether this tool should be deferred and discovered via tool search. + A summary of the reasoning output from the model so far. - - `description: optional string` + - `type: "summary_text"` - Optional description of the custom tool, used to provide more context. + The type of the object. Always `summary_text`. - - `format: optional object { type } or object { definition, syntax, type }` + - `"summary_text"` - The input format for the custom tool. Default is unconstrained text. + - `type: "reasoning"` - - `Text object { type }` + The type of the object. Always `reasoning`. - Unconstrained free-form text. + - `"reasoning"` - - `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. + - `content: optional array of object { text, type }` - - `definition: string` + Reasoning text content. - The grammar definition. + - `text: string` - - `syntax: "lark" or "regex"` + The reasoning text from the model. - The syntax of the grammar definition. One of `lark` or `regex`. + - `type: "reasoning_text"` - - `"lark"` + The type of the reasoning text. Always `reasoning_text`. - - `"regex"` + - `"reasoning_text"` - - `type: "grammar"` + - `encrypted_content: optional string` - Grammar format. Always `grammar`. + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - - `"grammar"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `type: "namespace"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The type of the tool. Always `namespace`. + - `"in_progress"` - - `"namespace"` + - `"completed"` - - `ToolSearch object { type, description, execution, parameters }` + - `"incomplete"` - Hosted or BYOT tool search configuration for deferred tools. + - `Program object { id, call_id, code, 3 more }` - - `type: "tool_search"` + - `id: string` - The type of the tool. Always `tool_search`. + The unique ID of the program item. - - `"tool_search"` + - `call_id: string` - - `description: optional string` + The stable call ID of the program item. - Description shown to the model for a client-executed tool search tool. + - `code: string` - - `execution: optional "server" or "client"` + The JavaScript source executed by programmatic tool calling. - Whether tool search is executed by the server or by the client. + - `fingerprint: string` - - `"server"` + Opaque program replay fingerprint that must be round-tripped. - - `"client"` + - `type: "program"` - - `parameters: optional unknown` + The type of the item. Always `program`. - Parameter schema for a client-executed tool search tool. + - `"program"` - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + - `agent: optional object { agent_name }` - 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 agent that produced this item. - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `agent_name: string` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + The canonical name of the agent that produced this item. - - `"web_search_preview"` + - `ProgramOutput object { id, call_id, result, 3 more }` - - `"web_search_preview_2025_03_11"` + - `id: string` - - `search_content_types: optional array of "text" or "image"` + The unique ID of the program output item. - - `"text"` + - `call_id: string` - - `"image"` + The call ID of the program item. - - `search_context_size: optional "low" or "medium" or "high"` + - `result: 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 result produced by the program item. - - `"low"` + - `status: "completed" or "incomplete"` - - `"medium"` + The terminal status of the program output item. - - `"high"` + - `"completed"` - - `user_location: optional object { type, city, country, 2 more }` + - `"incomplete"` - The user's location. + - `type: "program_output"` - - `type: "approximate"` + The type of the item. Always `program_output`. - The type of location approximation. Always `approximate`. + - `"program_output"` - - `"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`. + - `ToolSearchCall object { id, arguments, call_id, 5 more }` - - `region: optional string` + - `id: string` - Free text input for the region of the user, e.g. `California`. + The unique ID of the tool search call item. - - `timezone: optional string` + - `arguments: unknown` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + Arguments used for the tool search call. - - `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 tool search call generated by the model. - - `type: "apply_patch"` + - `execution: "server" or "client"` - The type of the tool. Always `apply_patch`. + Whether tool search was executed by the server or by the client. - - `"apply_patch"` + - `"server"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"client"` - The tool invocation context(s). + - `status: "in_progress" or "completed" or "incomplete"` - - `"direct"` + The status of the tool search call item that was recorded. - - `"programmatic"` + - `"in_progress"` - - `type: "tool_search_output"` + - `"completed"` - The item type. Always `tool_search_output`. + - `"incomplete"` - - `"tool_search_output"` + - `type: "tool_search_call"` - - `id: optional string` + The type of the item. Always `tool_search_call`. - The unique ID of this tool search output. + - `"tool_search_call"` - `agent: optional object { agent_name }` @@ -136142,11 +134221,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. @@ -136154,9 +134243,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 output. + The status of the tool search output item that was recorded. - `"in_progress"` @@ -136164,17 +134253,9 @@ 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` - A list of additional tools made available at this item. + The loaded tool definitions returned by tool search. - `Function object { name, parameters, strict, 5 more }` @@ -136437,7 +134518,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-web-search). + [web search tool](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -136497,7 +134578,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -136549,7 +134630,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -136695,8 +134776,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`. @@ -136741,19 +134854,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `background: optional "transparent" or "opaque" or "auto"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. - - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. - - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - `"transparent"` @@ -136782,13 +134884,13 @@ curl -X POST https://api.openai.com/v1/responses/compact \ Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `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-2" or 3 more` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` The image generation model to use. Default: `gpt-image-1`. @@ -136796,14 +134898,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"gpt-image-1-mini"` - - `"gpt-image-2"` - - - `"gpt-image-2-2026-04-21"` - - `"gpt-image-1.5"` - - `"chatgpt-image-latest"` - - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -136894,1061 +134990,417 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/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](https://platform.openai.com/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 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](https://platform.openai.com/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 - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. - - - `status: optional "in_progress" or "completed" or "incomplete"` - - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `Compaction object { encrypted_content, type, id, agent }` - - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/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`. + - `type: "container_auto"` - - `"shell_call"` + Automatically creates a container for this request - - `id: optional string` + - `"container_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 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 }` + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `caller_id: string` + - `skills: optional array of BetaSkillReference or BetaInlineSkill` - The call ID of the program item that produced this tool call. + An optional list of skills referenced by id or inline data. - - `type: "program"` + - `BetaSkillReference object { skill_id, type, version }` - The caller type. Always `program`. + - `skill_id: string` - - `"program"` + The ID of the referenced skill. - - `environment: optional BetaLocalEnvironment or BetaContainerReference` + - `type: "skill_reference"` - The environment to execute the shell commands in. + References a skill created with the /v1/skills endpoint. - - `BetaLocalEnvironment object { type, skills }` + - `"skill_reference"` - - `BetaContainerReference object { container_id, type }` + - `version: optional string` - - `status: optional "in_progress" or "completed" or "incomplete"` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `BetaInlineSkill object { description, name, source, type }` - - `"in_progress"` + - `description: string` - - `"completed"` + The description of the skill. - - `"incomplete"` + - `name: string` - - `ShellCallOutput object { call_id, output, type, 5 more }` + The name of the skill. - The streamed output items emitted by a shell tool call. + - `source: BetaInlineSkillSource` - - `call_id: string` + Inline skill payload - The unique ID of the shell tool call generated by the model. + - `data: string` - - `output: array of BetaResponseFunctionShellCallOutputContent` + Base64-encoded skill zip bundle. - Captured chunks of stdout and stderr output, along with their associated outcomes. + - `media_type: "application/zip"` - - `outcome: object { type } or object { exit_code, type }` + The media type of the inline skill payload. Must be `application/zip`. - The exit or timeout outcome associated with this shell call. + - `"application/zip"` - - `Timeout object { type }` + - `type: "base64"` - Indicates that the shell call exceeded its configured time limit. + The type of the inline skill source. Must be `base64`. - - `type: "timeout"` + - `"base64"` - The outcome type. Always `timeout`. + - `type: "inline"` - - `"timeout"` + Defines an inline skill for this request. - - `Exit object { exit_code, type }` + - `"inline"` - Indicates that the shell commands finished and returned an exit code. + - `BetaLocalEnvironment object { type, skills }` - - `exit_code: number` + - `type: "local"` - The exit code returned by the shell process. + Use a local computer environment. - - `type: "exit"` + - `"local"` - The outcome type. Always `exit`. + - `skills: optional array of BetaLocalSkill` - - `"exit"` + An optional list of skills. - - `stderr: string` + - `description: string` - Captured stderr output for the shell call. + The description of the skill. - - `stdout: string` + - `name: string` - Captured stdout output for the shell call. + The name of the skill. - - `type: "shell_call_output"` + - `path: string` - The type of the item. Always `shell_call_output`. + The path to the directory containing the skill. - - `"shell_call_output"` + - `BetaContainerReference object { container_id, type }` - - `id: optional string` + - `container_id: string` - The unique ID of the shell tool call output. Populated when this item is returned via API. + The ID of the referenced container. - - `agent: optional object { agent_name }` + - `type: "container_reference"` - The agent that produced this item. + References a container created with the /v1/containers endpoint - - `agent_name: string` + - `"container_reference"` - The canonical name of the agent that produced this item. + - `Custom object { name, type, allowed_callers, 3 more }` - - `caller: optional object { type } or object { caller_id, type }` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - The execution context that produced this tool call. + - `name: string` - - `Direct object { type }` + The name of the custom tool, used to identify it in tool calls. - - `type: "direct"` + - `type: "custom"` - The caller type. Always `direct`. + The type of the custom tool. Always `custom`. - - `"direct"` + - `"custom"` - - `Program object { caller_id, type }` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `caller_id: string` + The tool invocation context(s). - The call ID of the program item that produced this tool call. + - `"direct"` - - `type: "program"` + - `"programmatic"` - The caller type. Always `program`. + - `defer_loading: optional boolean` - - `"program"` + Whether this tool should be deferred and discovered via tool search. - - `max_output_length: optional number` + - `description: optional string` - The maximum number of UTF-8 characters captured for this shell call's combined output. + Optional description of the custom tool, used to provide more context. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `format: optional object { type } or object { definition, syntax, type }` - The status of the shell call output. + The input format for the custom tool. Default is unconstrained text. - - `"in_progress"` + - `Text object { type }` - - `"completed"` + Unconstrained free-form text. - - `"incomplete"` + - `type: "text"` - - `ApplyPatchCall object { call_id, operation, status, 4 more }` + Unconstrained text format. Always `text`. - A tool call representing a request to create, delete, or update files using diff patches. + - `"text"` - - `call_id: string` + - `Grammar object { definition, syntax, type }` - The unique ID of the apply patch tool call generated by the model. + A grammar defined by the user. - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + - `definition: string` - The specific create, delete, or update instruction for the apply_patch tool call. + The grammar definition. - - `CreateFile object { diff, path, type }` + - `syntax: "lark" or "regex"` - Instruction for creating a new file via the apply_patch tool. + The syntax of the grammar definition. One of `lark` or `regex`. - - `diff: string` + - `"lark"` - Unified diff content to apply when creating the file. + - `"regex"` - - `path: string` + - `type: "grammar"` - Path of the file to create relative to the workspace root. + Grammar format. Always `grammar`. - - `type: "create_file"` + - `"grammar"` - The operation type. Always `create_file`. + - `Namespace object { description, name, tools, type }` - - `"create_file"` + Groups function/custom tools under a shared namespace. - - `DeleteFile object { path, type }` + - `description: string` - Instruction for deleting an existing file via the apply_patch tool. + A description of the namespace shown to the model. - - `path: string` + - `name: string` - Path of the file to delete relative to the workspace root. + The namespace name used in tool calls (for example, `crm`). - - `type: "delete_file"` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - The operation type. Always `delete_file`. + The function/custom tools available inside this namespace. - - `"delete_file"` + - `Function object { name, type, allowed_callers, 5 more }` - - `UpdateFile object { diff, path, type }` + - `name: string` - Instruction for updating an existing file via the apply_patch tool. + - `type: "function"` - - `diff: string` + - `"function"` - Unified diff content to apply to the existing file. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `path: string` + The tool invocation context(s). - Path of the file to update relative to the workspace root. + - `"direct"` - - `type: "update_file"` + - `"programmatic"` - The operation type. Always `update_file`. + - `defer_loading: optional boolean` - - `"update_file"` + Whether this function should be deferred and discovered via tool search. - - `status: "in_progress" or "completed"` + - `description: optional string` - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `output_schema: optional map[unknown]` - - `"in_progress"` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `"completed"` + - `parameters: optional unknown` - - `type: "apply_patch_call"` + - `strict: optional boolean` - The type of the item. Always `apply_patch_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. - - `"apply_patch_call"` + - `Custom object { name, type, allowed_callers, 3 more }` - - `id: optional string` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `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"` - - `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 }` + - `"direct"` - - `type: "direct"` + - `"programmatic"` - The caller type. Always `direct`. + - `defer_loading: optional boolean` - - `"direct"` + Whether this tool should be deferred and discovered via tool search. - - `Program object { caller_id, type }` + - `description: optional string` - - `caller_id: string` + Optional description of the custom tool, used to provide more context. - The call ID of the program item that produced this tool call. + - `format: optional object { type } or object { definition, syntax, type }` - - `type: "program"` + The input format for the custom tool. Default is unconstrained text. - The caller type. Always `program`. + - `Text object { type }` - - `"program"` + Unconstrained free-form text. - - `ApplyPatchCallOutput object { call_id, status, type, 4 more }` + - `type: "text"` - The streamed output emitted by an apply patch tool call. + Unconstrained text format. Always `text`. - - `call_id: string` + - `"text"` - The unique ID of the apply patch tool call generated by the model. + - `Grammar object { definition, syntax, type }` - - `status: "completed" or "failed"` + A grammar defined by the user. - The status of the apply patch tool call output. One of `completed` or `failed`. + - `definition: string` - - `"completed"` + The grammar definition. - - `"failed"` + - `syntax: "lark" or "regex"` - - `type: "apply_patch_call_output"` + The syntax of the grammar definition. One of `lark` or `regex`. - The type of the item. Always `apply_patch_call_output`. + - `"lark"` - - `"apply_patch_call_output"` + - `"regex"` - - `id: optional string` + - `type: "grammar"` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + 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"` - - `caller: optional object { type } or object { caller_id, type }` + - `ToolSearch object { type, description, execution, parameters }` - The execution context that produced this tool call. + Hosted or BYOT tool search configuration for deferred tools. - - `Direct object { type }` + - `type: "tool_search"` - - `type: "direct"` + The type of the tool. Always `tool_search`. - The caller type. Always `direct`. + - `"tool_search"` - - `"direct"` + - `description: optional string` - - `Program object { caller_id, type }` + Description shown to the model for a client-executed tool search tool. - - `caller_id: string` + - `execution: optional "server" or "client"` - The call ID of the program item that produced this tool call. + Whether tool search is executed by the server or by the client. - - `type: "program"` + - `"server"` - The caller type. Always `program`. + - `"client"` - - `"program"` + - `parameters: optional unknown` - - `output: optional string` + Parameter schema for a client-executed tool search tool. - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - - `McpListTools object { id, server_label, tools, 3 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 list of tools available on an MCP server. + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `id: string` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - The unique ID of the list. + - `"web_search_preview"` - - `server_label: string` + - `"web_search_preview_2025_03_11"` - The label of the MCP server. + - `search_content_types: optional array of "text" or "image"` - - `tools: array of object { input_schema, name, annotations, description }` + - `"text"` - The tools available on the server. + - `"image"` - - `input_schema: unknown` + - `search_context_size: optional "low" or "medium" or "high"` - The JSON schema describing the tool's input. + 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. - - `name: string` + - `"low"` - The name of the tool. + - `"medium"` - - `annotations: optional unknown` + - `"high"` - Additional annotations about the tool. + - `user_location: optional object { type, city, country, 2 more }` - - `description: optional string` + The user's location. - The description of the tool. + - `type: "approximate"` - - `type: "mcp_list_tools"` + The type of location approximation. Always `approximate`. - The type of the item. Always `mcp_list_tools`. + - `"approximate"` - - `"mcp_list_tools"` + - `city: optional string` - - `agent: optional object { agent_name }` + Free text input for the city of the user, e.g. `San Francisco`. - The agent that produced this item. + - `country: optional string` - - `agent_name: string` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The canonical name of the agent that produced this item. + - `region: optional string` - - `error: optional string` + Free text input for the region of the user, e.g. `California`. - Error message if the server could not list tools. + - `timezone: optional string` - - `McpApprovalRequest object { id, arguments, name, 3 more }` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - A request for human approval of a tool invocation. + - `ApplyPatch object { type, allowed_callers }` - - `id: string` + Allows the assistant to create, delete, or update files using unified diffs. - The unique ID of the approval request. + - `type: "apply_patch"` - - `arguments: string` + The type of the tool. Always `apply_patch`. - A JSON string of arguments for the tool. + - `"apply_patch"` - - `name: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The name of the tool to run. + The tool invocation context(s). - - `server_label: string` + - `"direct"` - The label of the MCP server making the request. + - `"programmatic"` - - `type: "mcp_approval_request"` + - `type: "tool_search_output"` - The type of the item. Always `mcp_approval_request`. + The type of the item. Always `tool_search_output`. - - `"mcp_approval_request"` + - `"tool_search_output"` - `agent: optional object { agent_name }` @@ -137958,1049 +135410,1060 @@ 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 }` - - A response to an MCP approval request. - - - `approval_request_id: string` - - The ID of the approval request being answered. - - - `approve: boolean` + - `created_by: optional string` - Whether the request was approved. + The identifier of the actor that created the item. - - `type: "mcp_approval_response"` + - `AdditionalTools object { id, role, tools, 2 more }` - The type of the item. Always `mcp_approval_response`. + - `id: string` - - `"mcp_approval_response"` + The unique ID of the additional tools item. - - `id: optional string` + - `role: "unknown" or "user" or "assistant" or 5 more` - The unique ID of the approval response + The role that provided the additional tools. - - `agent: optional object { agent_name }` + - `"unknown"` - The agent that produced this item. + - `"user"` - - `agent_name: string` + - `"assistant"` - The canonical name of the agent that produced this item. + - `"system"` - - `reason: optional string` + - `"critic"` - Optional reason for the decision. + - `"discriminator"` - - `McpCall object { id, arguments, name, 7 more }` + - `"developer"` - An invocation of a tool on an MCP server. + - `"tool"` - - `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 tool call. + The additional tool definitions made available at this item. - - `arguments: string` + - `Function object { name, parameters, strict, 5 more }` - A JSON string of the arguments passed to the tool. + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - `name: string` - The name of the tool that was run. - - - `server_label: string` + The name of the function to call. - The label of the MCP server running the tool. + - `parameters: map[unknown]` - - `type: "mcp_call"` + A JSON schema object describing the parameters of the function. - The type of the item. Always `mcp_call`. + - `strict: boolean` - - `"mcp_call"` + Whether strict parameter validation is enforced for this function tool. - - `agent: optional object { agent_name }` + - `type: "function"` - The agent that produced this item. + The type of the function tool. Always `function`. - - `agent_name: string` + - `"function"` - The canonical name of the agent that produced this item. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `approval_request_id: optional string` + The tool invocation context(s). - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + - `"direct"` - - `error: optional string` + - `"programmatic"` - The error from the tool call, if any. + - `defer_loading: optional boolean` - - `output: optional string` + Whether this function is deferred and loaded via tool search. - The output from the tool call. + - `description: optional string` - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + A description of the function. Used by the model to determine whether or not to call the function. - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `output_schema: optional map[unknown]` - - `"in_progress"` + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `"completed"` + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - - `"incomplete"` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `"calling"` + - `type: "file_search"` - - `"failed"` + The type of the file search tool. Always `file_search`. - - `CustomToolCallOutput object { call_id, output, type, 3 more }` + - `"file_search"` - The output of a custom tool call from your code, being sent back to the model. + - `vector_store_ids: array of string` - - `call_id: string` + The IDs of the vector stores to search. - The call ID, used to map this custom tool call output to a custom tool call. + - `filters: optional object { key, type, value } or object { filters, type }` - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + A filter to apply. - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `ComparisonFilter object { key, type, value }` - - `StringOutput = string` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - A string of the output of the custom tool call. + - `key: string` - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + The key to compare against the value. - Text, image, or file output of the custom tool call. + - `type: "eq" or "ne" or "gt" or 5 more` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - A text 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 - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `"eq"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `"ne"` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `"gt"` - A file input to the model. + - `"gte"` - - `type: "custom_tool_call_output"` + - `"lt"` - The type of the custom tool call output. Always `custom_tool_call_output`. + - `"lte"` - - `"custom_tool_call_output"` + - `"in"` - - `id: optional string` + - `"nin"` - The unique ID of the custom tool call output in the OpenAI platform. + - `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 produced this item. + - `string` - - `agent_name: string` + - `number` - The canonical name of the agent that produced this item. + - `boolean` - - `caller: optional object { type } or object { caller_id, type }` + - `array of string or number` - The execution context that produced this tool call. + - `string` - - `Direct object { type }` + - `number` - - `type: "direct"` + - `CompoundFilter object { filters, type }` - The caller type. Always `direct`. + Combine multiple filters using `and` or `or`. - - `"direct"` + - `filters: array of object { key, type, value } or unknown` - - `Program object { caller_id, type }` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `caller_id: string` + - `ComparisonFilter object { key, type, value }` - The call ID of the program item that produced this tool call. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `type: "program"` + - `key: string` - The caller type. Always `program`. + The key to compare against the value. - - `"program"` + - `type: "eq" or "ne" or "gt" or 5 more` - - `CustomToolCall object { call_id, input, name, 5 more }` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - A call to a custom tool created by the model. + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `call_id: string` + - `"eq"` - An identifier used to map this custom tool call to a tool call output. + - `"ne"` - - `input: string` + - `"gt"` - The input for the custom tool call generated by the model. + - `"gte"` - - `name: string` + - `"lt"` - The name of the custom tool being called. + - `"lte"` - - `type: "custom_tool_call"` + - `"in"` - The type of the custom tool call. Always `custom_tool_call`. + - `"nin"` - - `"custom_tool_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 custom tool call in the OpenAI platform. + - `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`. - - `"direct"` + - `"and"` - - `Program object { caller_id, type }` + - `"or"` - - `caller_id: string` + - `max_num_results: optional number` - The call ID of the program item that produced this tool call. + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `type: "program"` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `"program"` + Ranking options for search. - - `namespace: optional string` + - `hybrid_search: optional object { embedding_weight, text_weight }` - The namespace of the custom tool being called. + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `CompactionTrigger object { type, agent }` + - `embedding_weight: number` - Compacts the current context. Must be the final input item. + The weight of the embedding in the reciprocal ranking fusion. - - `type: "compaction_trigger"` + - `text_weight: number` - The type of the item. Always `compaction_trigger`. + The weight of the text in the reciprocal ranking fusion. - - `"compaction_trigger"` + - `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` - - `ItemReference object { id, agent, 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 internal identifier for an item to reference. + - `Computer object { type }` - - `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 item to reference. + - `type: "computer"` - - `agent: optional object { agent_name }` + The type of the computer tool. Always `computer`. - The agent that produced this item. + - `"computer"` - - `agent_name: string` + - `ComputerUsePreview object { display_height, display_width, environment, 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). - - `type: optional "item_reference"` + - `display_height: number` - The type of item to reference. Always `item_reference`. + The height of the computer display. - - `"item_reference"` + - `display_width: number` - - `Program object { id, call_id, code, 3 more }` + The width of the computer display. - - `id: string` + - `environment: "windows" or "mac" or "linux" or 2 more` - The unique ID of this program item. + The type of computer environment to control. - - `call_id: string` + - `"windows"` - The stable call ID of the program item. + - `"mac"` - - `code: string` + - `"linux"` - The JavaScript source executed by programmatic tool calling. + - `"ubuntu"` - - `fingerprint: string` + - `"browser"` - Opaque program replay fingerprint that must be round-tripped. + - `type: "computer_use_preview"` - - `type: "program"` + The type of the computer use tool. Always `computer_use_preview`. - The item type. Always `program`. + - `"computer_use_preview"` - - `"program"` + - `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 produced this item. + - `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"` - - `ProgramOutput object { id, call_id, result, 3 more }` + - `"web_search_2025_08_26"` - - `id: string` + - `filters: optional object { allowed_domains }` - The unique ID of this program output item. + Filters for the search. - - `call_id: string` + - `allowed_domains: optional array of string` - The call ID of the program item. + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `result: string` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - The result produced by the program item. + - `search_context_size: optional "low" or "medium" or "high"` - - `status: "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 terminal status of the program output. + - `"low"` - - `"completed"` + - `"medium"` - - `"incomplete"` + - `"high"` - - `type: "program_output"` + - `user_location: optional object { city, country, region, 2 more }` - The item type. Always `program_output`. + The approximate location of the user. - - `"program_output"` + - `city: optional string` - - `agent: optional object { agent_name }` + Free text input for the city of the user, e.g. `San Francisco`. - The agent that produced this item. + - `country: optional string` - - `agent_name: string` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The canonical name of the agent that produced this item. + - `region: optional string` - - `metadata: map[string]` + Free text input for the region of the user, e.g. `California`. - 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. + - `timezone: optional string` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` + - `type: optional "approximate"` - 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](https://platform.openai.com/docs/models) - to browse and compare available models. + The type of location approximation. Always `approximate`. - - `"gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more` + - `"approximate"` - 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](https://platform.openai.com/docs/models) - to browse and compare available models. + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `"gpt-5.6-sol"` + 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.6-terra"` + - `server_label: string` - - `"gpt-5.6-luna"` + A label for this MCP server, used to identify it in tool calls. - - `"gpt-5.4"` + - `type: "mcp"` - - `"gpt-5.4-mini"` + The type of the MCP tool. Always `mcp`. - - `"gpt-5.4-nano"` + - `"mcp"` - - `"gpt-5.4-mini-2026-03-17"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"gpt-5.4-nano-2026-03-17"` + The tool invocation context(s). - - `"gpt-5.3-chat-latest"` + - `"direct"` - - `"gpt-5.2"` + - `"programmatic"` - - `"gpt-5.2-2025-12-11"` + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `"gpt-5.2-chat-latest"` + List of allowed tool names or a filter object. - - `"gpt-5.2-pro"` + - `McpAllowedTools = array of string` - - `"gpt-5.2-pro-2025-12-11"` + A string array of allowed tool names - - `"gpt-5.1"` + - `McpToolFilter object { read_only, tool_names }` - - `"gpt-5.1-2025-11-13"` + A filter object to specify which tools are allowed. - - `"gpt-5.1-codex"` + - `read_only: optional boolean` - - `"gpt-5.1-mini"` + 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-5.1-chat-latest"` + - `tool_names: optional array of string` - - `"gpt-5"` + List of allowed tool names. - - `"gpt-5-mini"` + - `authorization: optional string` - - `"gpt-5-nano"` + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - - `"gpt-5-2025-08-07"` + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `"gpt-5-mini-2025-08-07"` + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). - - `"gpt-5-nano-2025-08-07"` + Currently supported `connector_id` values are: - - `"gpt-5-chat-latest"` + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - - `"gpt-4.1"` + - `"connector_dropbox"` - - `"gpt-4.1-mini"` + - `"connector_gmail"` - - `"gpt-4.1-nano"` + - `"connector_googlecalendar"` - - `"gpt-4.1-2025-04-14"` + - `"connector_googledrive"` - - `"gpt-4.1-mini-2025-04-14"` + - `"connector_microsoftteams"` - - `"gpt-4.1-nano-2025-04-14"` + - `"connector_outlookcalendar"` - - `"o4-mini"` + - `"connector_outlookemail"` - - `"o4-mini-2025-04-16"` + - `"connector_sharepoint"` - - `"o3"` + - `defer_loading: optional boolean` - - `"o3-2025-04-16"` + Whether this MCP tool is deferred and discovered via tool search. - - `"o3-mini"` + - `headers: optional map[string]` - - `"o3-mini-2025-01-31"` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `"o1"` + - `require_approval: optional object { always, never } or "always" or "never"` - - `"o1-2024-12-17"` + Specify which of the MCP server's tools require approval. - - `"o1-preview"` + - `McpToolApprovalFilter object { always, never }` - - `"o1-preview-2024-09-12"` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `"o1-mini"` + - `always: optional object { read_only, tool_names }` - - `"o1-mini-2024-09-12"` + A filter object to specify which tools are allowed. - - `"gpt-4o"` + - `read_only: optional boolean` - - `"gpt-4o-2024-11-20"` + 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-4o-2024-08-06"` + - `tool_names: optional array of string` - - `"gpt-4o-2024-05-13"` + List of allowed tool names. - - `"gpt-4o-audio-preview"` + - `never: optional object { read_only, tool_names }` - - `"gpt-4o-audio-preview-2024-10-01"` + A filter object to specify which tools are allowed. - - `"gpt-4o-audio-preview-2024-12-17"` + - `read_only: optional boolean` - - `"gpt-4o-audio-preview-2025-06-03"` + 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-4o-mini-audio-preview"` + - `tool_names: optional array of string` - - `"gpt-4o-mini-audio-preview-2024-12-17"` + List of allowed tool names. - - `"gpt-4o-search-preview"` + - `McpToolApprovalSetting = "always" or "never"` - - `"gpt-4o-mini-search-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-4o-search-preview-2025-03-11"` + - `"always"` - - `"gpt-4o-mini-search-preview-2025-03-11"` + - `"never"` - - `"chatgpt-4o-latest"` + - `server_description: optional string` - - `"codex-mini-latest"` + Optional description of the MCP server, used to provide more context. - - `"gpt-4o-mini"` + - `server_url: optional string` - - `"gpt-4o-mini-2024-07-18"` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `"gpt-4-turbo"` + - `tunnel_id: optional string` - - `"gpt-4-turbo-2024-04-09"` + 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-4-0125-preview"` + - `CodeInterpreter object { container, type, allowed_callers }` - - `"gpt-4-turbo-preview"` + A tool that runs Python code to help generate a response to a prompt. - - `"gpt-4-1106-preview"` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `"gpt-4-vision-preview"` + 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-4"` + - `string` - - `"gpt-4-0314"` + The container ID. - - `"gpt-4-0613"` + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - - `"gpt-4-32k"` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `"gpt-4-32k-0314"` + - `type: "auto"` - - `"gpt-4-32k-0613"` + Always `auto`. - - `"gpt-3.5-turbo"` + - `"auto"` - - `"gpt-3.5-turbo-16k"` + - `file_ids: optional array of string` - - `"gpt-3.5-turbo-0301"` + An optional list of uploaded files to make available to your code. - - `"gpt-3.5-turbo-0613"` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `"gpt-3.5-turbo-1106"` + The memory limit for the code interpreter container. - - `"gpt-3.5-turbo-0125"` + - `"1g"` - - `"gpt-3.5-turbo-16k-0613"` + - `"4g"` - - `"o1-pro"` + - `"16g"` - - `"o1-pro-2025-03-19"` + - `"64g"` - - `"o3-pro"` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `"o3-pro-2025-06-10"` + Network access policy for the container. - - `"o3-deep-research"` + - `BetaContainerNetworkPolicyDisabled object { type }` - - `"o3-deep-research-2025-06-26"` + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `"o4-mini-deep-research"` + - `type: "code_interpreter"` - - `"o4-mini-deep-research-2025-06-26"` + The type of the code interpreter tool. Always `code_interpreter`. - - `"computer-use-preview"` + - `"code_interpreter"` - - `"computer-use-preview-2025-03-11"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"gpt-5-codex"` + The tool invocation context(s). - - `"gpt-5-pro"` + - `"direct"` - - `"gpt-5-pro-2025-10-06"` + - `"programmatic"` - - `"gpt-5.1-codex-max"` + - `ProgrammaticToolCalling object { type }` - - `string` + - `type: "programmatic_tool_calling"` - - `object: "response"` + The type of the tool. Always `programmatic_tool_calling`. - The object type of this resource - always set to `response`. + - `"programmatic_tool_calling"` - - `"response"` + - `ImageGeneration object { type, action, background, 9 more }` - - `output: array of BetaResponseOutputItem` + A tool that generates images using the GPT image models. - An array of content items generated by the model. + - `type: "image_generation"` - - 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 type of the image generation tool. Always `image_generation`. - - `BetaResponseOutputMessage object { id, content, role, 4 more }` + - `"image_generation"` - An output message from the model. + - `action: optional "generate" or "edit" or "auto"` - - `FileSearchCall object { id, queries, status, 3 more }` + Whether to generate a new image or edit an existing image. Default: `auto`. - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `"generate"` - - `id: string` + - `"edit"` - The unique ID of the file search tool call. + - `"auto"` - - `queries: array of string` + - `background: optional "transparent" or "opaque" or "auto"` - The queries used to search for files. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - - `status: "in_progress" or "searching" or "completed" or 2 more` + - `"transparent"` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `"opaque"` - - `"in_progress"` + - `"auto"` - - `"searching"` + - `input_fidelity: optional "high" or "low"` - - `"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`. - - `"incomplete"` + - `"high"` - - `"failed"` + - `"low"` - - `type: "file_search_call"` + - `input_image_mask: optional object { file_id, image_url }` - The type of the file search tool call. Always `file_search_call`. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `"file_search_call"` + - `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"` - - `results: optional array of object { attributes, file_id, filename, 2 more }` + The image generation model to use. Default: `gpt-image-1`. - The results of the file search tool call. + - `string` - - `attributes: optional map[string or number or boolean]` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. Keys are strings - with a maximum length of 64 characters. Values are strings with a maximum - length of 512 characters, booleans, or numbers. + The image generation model to use. Default: `gpt-image-1`. - - `string` + - `"gpt-image-1"` - - `number` + - `"gpt-image-1-mini"` - - `boolean` + - `"gpt-image-1.5"` - - `file_id: optional string` + - `moderation: optional "auto" or "low"` - The unique ID of the file. + Moderation level for the generated image. Default: `auto`. - - `filename: optional string` + - `"auto"` - The name of the file. + - `"low"` - - `score: optional number` + - `output_compression: optional number` - The relevance score of the file - a value between 0 and 1. + Compression level for the output image. Default: 100. - - `text: optional string` + - `output_format: optional "png" or "webp" or "jpeg"` - The text that was retrieved from the file. + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `FunctionCall object { arguments, call_id, name, 6 more }` + - `"png"` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `"webp"` - - `arguments: string` + - `"jpeg"` - A JSON string of the arguments to pass to the function. + - `partial_images: optional number` - - `call_id: string` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - The unique ID of the function tool call generated by the model. + - `quality: optional "low" or "medium" or "high" or "auto"` - - `name: string` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - The name of the function to run. + - `"low"` - - `type: "function_call"` + - `"medium"` - The type of the function tool call. Always `function_call`. + - `"high"` - - `"function_call"` + - `"auto"` - - `id: optional string` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - The unique ID of the function tool call. + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `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 }` - - `"direct"` + A tool that allows the model to execute shell commands in a local environment. - - `Program object { caller_id, type }` + - `type: "local_shell"` - - `caller_id: string` + The type of the local shell tool. Always `local_shell`. - The call ID of the program item that produced this tool call. + - `"local_shell"` - - `type: "program"` + - `Shell object { type, allowed_callers, environment }` - - `"program"` + A tool that allows the model to execute shell commands. - - `namespace: optional string` + - `type: "shell"` - The namespace of the function to run. + The type of the shell tool. Always `shell`. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"shell"` - 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"` - - `FunctionCallOutput object { id, call_id, output, 5 more }` + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - `id: string` + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - The unique ID of the function call tool output. + - `BetaLocalEnvironment object { type, skills }` - - `call_id: string` + - `BetaContainerReference object { container_id, type }` - The unique ID of the function tool call generated by the model. + - `Custom object { name, type, allowed_callers, 3 more }` - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - The output from the function call generated by your code. - Can be a string or an list of output content. + - `name: string` - - `StringOutput = string` + The name of the custom tool, used to identify it in tool calls. - A string of the output of the function call. + - `type: "custom"` - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + The type of the custom tool. Always `custom`. - Text, image, or file output of the function call. + - `"custom"` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `allowed_callers: optional array of "direct" or "programmatic"` - A text input to the model. + The tool invocation context(s). - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `"direct"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `"programmatic"` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `defer_loading: optional boolean` - A file input to the model. + Whether this tool should be deferred and discovered via tool search. - - `status: "in_progress" or "completed" or "incomplete"` + - `description: optional string` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + 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 }` - - `type: "function_call_output"` + Unconstrained free-form text. - The type of the function tool call output. Always `function_call_output`. + - `type: "text"` - - `"function_call_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` - - `caller: optional object { type } or object { caller_id, type }` + The grammar definition. - The execution context that produced this tool call. + - `syntax: "lark" or "regex"` - - `Direct object { type }` + The syntax of the grammar definition. One of `lark` or `regex`. - - `type: "direct"` + - `"lark"` - The caller type. Always `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. + - `Namespace object { description, name, tools, type }` - - `type: "program"` + Groups function/custom tools under a shared namespace. - The caller type. Always `program`. + - `description: string` - - `"program"` + A description of the namespace shown to the model. - - `created_by: optional string` + - `name: string` - The identifier of the actor that created the item. + The namespace name used in tool calls (for example, `crm`). - - `AgentMessage object { id, author, content, 3 more }` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - - `id: string` + The function/custom tools available inside this namespace. - The unique ID of the agent message. + - `Function object { name, type, allowed_callers, 5 more }` - - `author: string` + - `name: string` - The sending agent identity. + - `type: "function"` - - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` + - `"function"` - Encrypted content sent between agents. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + The tool invocation context(s). - A text input to the model. + - `"direct"` - - `BetaResponseOutputText object { annotations, text, type, logprobs }` + - `"programmatic"` - A text output from the model. + - `defer_loading: optional boolean` - - `Text object { text, type }` + Whether this function should be deferred and discovered via tool search. - A text content. + - `description: optional string` - - `text: string` + - `output_schema: optional map[unknown]` - - `type: "text"` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `"text"` + - `parameters: optional unknown` - - `SummaryText object { text, type }` + - `strict: optional boolean` - A summary text from the model. + 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. - - `text: string` + - `Custom object { name, type, allowed_callers, 3 more }` - A summary of the reasoning output from the model so far. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `type: "summary_text"` + - `name: string` - The type of the object. Always `summary_text`. + The name of the custom tool, used to identify it in tool calls. - - `"summary_text"` + - `type: "custom"` - - `ReasoningText object { text, type }` + The type of the custom tool. Always `custom`. - Reasoning text from the model. + - `"custom"` - - `text: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The reasoning text from the model. + The tool invocation context(s). - - `type: "reasoning_text"` + - `"direct"` - The type of the reasoning text. Always `reasoning_text`. + - `"programmatic"` - - `"reasoning_text"` + - `defer_loading: optional boolean` - - `BetaResponseOutputRefusal object { refusal, type }` + Whether this tool should be deferred and discovered via tool search. - A refusal from the model. + - `description: optional string` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + Optional description of the custom tool, used to provide more context. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `format: optional object { type } or object { definition, syntax, type }` - - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` + The input format for the custom tool. Default is unconstrained text. - A screenshot of a computer. + - `Text object { type }` - - `detail: "low" or "high" or "auto" or "original"` + Unconstrained free-form text. - The detail level of the screenshot 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: string` + - `definition: string` - The identifier of an uploaded file that contains the screenshot. + The grammar definition. - - `image_url: string` + - `syntax: "lark" or "regex"` - The URL of the screenshot image. + The syntax of the grammar definition. One of `lark` or `regex`. - - `type: "computer_screenshot"` + - `"lark"` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + - `"regex"` - - `"computer_screenshot"` + - `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"` + - `type: "namespace"` - The breakpoint mode. Always `explicit`. + The type of the tool. Always `namespace`. - - `"explicit"` + - `"namespace"` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `ToolSearch object { type, description, execution, parameters }` - A file input to the model. + Hosted or BYOT tool search configuration for deferred tools. - - `EncryptedContent object { encrypted_content, type }` + - `type: "tool_search"` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + The type of the tool. Always `tool_search`. - - `encrypted_content: string` + - `"tool_search"` - Opaque encrypted content. + - `description: optional string` - - `type: "encrypted_content"` + Description shown to the model for a client-executed tool search tool. - The type of the input item. Always `encrypted_content`. + - `execution: optional "server" or "client"` - - `"encrypted_content"` + Whether tool search is executed by the server or by the client. - - `recipient: string` + - `"server"` - The destination agent identity. + - `"client"` - - `type: "agent_message"` + - `parameters: optional unknown` - The type of the item. Always `agent_message`. + Parameter schema for a client-executed tool search tool. - - `"agent_message"` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - - `agent: optional object { agent_name }` + 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 agent that produced this item. + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `agent_name: string` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - The canonical name of the agent that produced this item. + - `"web_search_preview"` - - `MultiAgentCall object { id, action, arguments, 3 more }` + - `"web_search_preview_2025_03_11"` - - `id: string` + - `search_content_types: optional array of "text" or "image"` - The unique ID of the multi-agent call item. + - `"text"` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `"image"` - The multi-agent action to execute. + - `search_context_size: optional "low" or "medium" or "high"` - - `"spawn_agent"` + 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. - - `"interrupt_agent"` + - `"low"` - - `"list_agents"` + - `"medium"` - - `"send_message"` + - `"high"` - - `"followup_task"` + - `user_location: optional object { type, city, country, 2 more }` - - `"wait_agent"` + The user's location. - - `arguments: string` + - `type: "approximate"` - The JSON string of arguments generated for the action. + The type of location approximation. Always `approximate`. - - `call_id: string` + - `"approximate"` - The unique ID linking this call to its output. + - `city: optional string` - - `type: "multi_agent_call"` + Free text input for the city of the user, e.g. `San Francisco`. - The type of the multi-agent call. Always `multi_agent_call`. + - `country: optional string` - - `"multi_agent_call"` + 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`. - - `MultiAgentCallOutput object { id, action, call_id, 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 multi-agent call output item. + - `type: "apply_patch"` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + The type of the tool. Always `apply_patch`. - The multi-agent action that produced this result. + - `"apply_patch"` - - `"spawn_agent"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"interrupt_agent"` + The tool invocation context(s). - - `"list_agents"` + - `"direct"` - - `"send_message"` + - `"programmatic"` - - `"followup_task"` + - `type: "additional_tools"` - - `"wait_agent"` + The type of the item. Always `additional_tools`. - - `call_id: string` + - `"additional_tools"` - The unique ID of the multi-agent call. + - `agent: optional object { agent_name }` - - `output: array of BetaResponseOutputText` + The agent that produced this item. - Text output returned by the multi-agent action. + - `agent_name: 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 canonical name of the agent that produced this item. - The annotations of the text output. + - `Compaction object { id, encrypted_content, type, 2 more }` - - `text: string` + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). - The text output from the model. + - `id: string` - - `type: "output_text"` + The unique ID of the compaction item. - The type of the output text. Always `output_text`. + - `encrypted_content: string` - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + The encrypted content that was produced by compaction. - - `type: "multi_agent_call_output"` + - `type: "compaction"` - The type of the multi-agent result. Always `multi_agent_call_output`. + The type of the item. Always `compaction`. - - `"multi_agent_call_output"` + - `"compaction"` - `agent: optional object { agent_name }` @@ -139010,101 +136473,116 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `WebSearchCall object { id, action, status, 2 more }` + - `created_by: optional string` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + 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 web search tool call. + The unique ID of the image generation call. - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + - `result: 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). + The generated image encoded in base64. - - `Search object { type, queries, query, sources }` + - `status: "in_progress" or "completed" or "generating" or "failed"` - Action type "search" - Performs a web search query. + The status of the image generation call. - - `type: "search"` + - `"in_progress"` - The action type. + - `"completed"` - - `"search"` + - `"generating"` - - `queries: optional array of string` + - `"failed"` - The search queries. + - `type: "image_generation_call"` - - `query: optional string` + The type of the image generation call. Always `image_generation_call`. - The search query. + - `"image_generation_call"` - - `sources: optional array of object { type, url }` + - `agent: optional object { agent_name }` - The sources used in the search. + The agent that produced this item. - - `type: "url"` + - `agent_name: string` - The type of source. Always `url`. + The canonical name of the agent that produced this item. - - `"url"` + - `CodeInterpreterCall object { id, code, container_id, 4 more }` - - `url: string` + A tool call to run code. - The URL of the source. + - `id: string` - - `OpenPage object { type, url }` + The unique ID of the code interpreter tool call. - Action type "open_page" - Opens a specific URL from search results. + - `code: string` - - `type: "open_page"` + The code to run, or null if not available. - The action type. + - `container_id: string` - - `"open_page"` + The ID of the container used to run the code. - - `url: optional string` + - `outputs: array of object { logs, type } or object { type, url }` - The URL opened by the model. + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `FindInPage object { pattern, type, url }` + - `Logs object { logs, type }` - Action type "find_in_page": Searches for a pattern within a loaded page. + The logs output from the code interpreter. - - `pattern: string` + - `logs: string` - The pattern or text to search for within the page. + The logs output from the code interpreter. - - `type: "find_in_page"` + - `type: "logs"` - The action type. + The type of the output. Always `logs`. - - `"find_in_page"` + - `"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 page searched for the pattern. + The URL of the image output from the code interpreter. - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - The status of the web search tool call. + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - `"in_progress"` - - `"searching"` - - `"completed"` + - `"incomplete"` + + - `"interpreting"` + - `"failed"` - - `type: "web_search_call"` + - `type: "code_interpreter_call"` - The type of the web search tool call. Always `web_search_call`. + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `"web_search_call"` + - `"code_interpreter_call"` - `agent: optional object { agent_name }` @@ -139114,60 +136592,63 @@ 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 }` + - `LocalShellCall object { id, action, call_id, 3 more }` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + A tool call to run a command on the local shell. - `id: string` - The unique ID of the computer call. + The unique ID of the local shell call. - - `call_id: string` + - `action: object { command, env, type, 3 more }` - An identifier used when responding to the tool call with output. + Execute a shell command on the server. - - `pending_safety_checks: array of object { id, code, message }` + - `command: array of string` - The pending safety checks for the computer call. + The command to run. - - `id: string` + - `env: map[string]` - The ID of the pending safety check. + Environment variables to set for the command. - - `code: optional string` + - `type: "exec"` - The type of the pending safety check. + The type of the local shell action. Always `exec`. - - `message: optional string` + - `"exec"` - Details about the pending safety check. + - `timeout_ms: optional number` - - `status: "in_progress" or "completed" or "incomplete"` + Optional timeout in milliseconds for the command. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `user: optional string` - - `"in_progress"` + Optional user to run the command as. - - `"completed"` + - `working_directory: optional string` - - `"incomplete"` + Optional working directory to run the command in. - - `type: "computer_call"` + - `call_id: string` - The type of the computer call. Always `computer_call`. + The unique ID of the local shell tool call generated by the model. - - `"computer_call"` + - `status: "in_progress" or "completed" or "incomplete"` - - `action: optional BetaComputerAction` + The status of the local shell call. - A click action. + - `"in_progress"` - - `actions: optional BetaComputerActionList` + - `"completed"` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `"incomplete"` + + - `type: "local_shell_call"` + + The type of the local shell call. Always `local_shell_call`. + + - `"local_shell_call"` - `agent: optional object { agent_name }` @@ -139177,230 +136658,205 @@ curl -X POST https://api.openai.com/v1/responses/compact \ 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"` + - `LocalShellCallOutput object { id, output, type, 2 more }` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + The output of a local shell tool call. - - `"completed"` + - `id: string` - - `"incomplete"` + The unique ID of the local shell tool call generated by the model. - - `"failed"` + - `output: string` - - `"in_progress"` + A JSON string of the output of the local shell tool call. - - `type: "computer_call_output"` + - `type: "local_shell_call_output"` - The type of the computer tool call output. Always `computer_call_output`. + The type of the local shell tool call output. Always `local_shell_call_output`. - - `"computer_call_output"` + - `"local_shell_call_output"` - - `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` + - `status: optional "in_progress" or "completed" or "incomplete"` - The type of the pending safety check. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `message: optional string` + - `"in_progress"` - Details about the pending safety check. + - `"completed"` - - `agent: optional object { agent_name }` + - `"incomplete"` - The agent that produced this item. + - `ShellCall object { id, action, call_id, 6 more }` - - `agent_name: string` + A tool call that executes one or more shell commands in a managed environment. - The canonical name of the agent that produced this item. + - `id: string` - - `created_by: optional string` + The unique ID of the shell tool call. Populated when this item is returned via API. - The identifier of the actor that created the item. + - `action: object { commands, max_output_length, timeout_ms }` - - `Reasoning object { id, summary, type, 4 more }` + The shell commands and limits that describe how to run the tool 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](https://platform.openai.com/docs/guides/conversation-state). + - `commands: array of string` - - `id: string` + - `max_output_length: number` - The unique identifier of the reasoning content. + Optional maximum number of characters to return from each command. - - `summary: array of object { text, type }` + - `timeout_ms: number` - Reasoning summary content. + Optional timeout in milliseconds for the commands. - - `text: string` + - `call_id: string` - A summary of the reasoning output from the model so far. + The unique ID of the shell tool call generated by the model. - - `type: "summary_text"` + - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` - The type of the object. Always `summary_text`. + Represents the use of a local environment to perform shell actions. - - `"summary_text"` + - `BetaResponseLocalEnvironment object { type }` - - `type: "reasoning"` + Represents the use of a local environment to perform shell actions. - The type of the object. Always `reasoning`. + - `type: "local"` - - `"reasoning"` + 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` - - `content: optional array of object { text, type }` + - `type: "container_reference"` - Reasoning text content. + The environment type. Always `container_reference`. - - `text: string` + - `"container_reference"` - The reasoning text from the model. + - `status: "in_progress" or "completed" or "incomplete"` - - `type: "reasoning_text"` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - The type of the reasoning text. Always `reasoning_text`. + - `"in_progress"` - - `"reasoning_text"` + - `"completed"` - - `encrypted_content: optional string` + - `"incomplete"` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `type: "shell_call"` - - `status: optional "in_progress" or "completed" or "incomplete"` + The type of the item. Always `shell_call`. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"shell_call"` - - `"in_progress"` + - `agent: optional object { agent_name }` - - `"completed"` + The agent that produced this item. - - `"incomplete"` + - `agent_name: string` - - `Program object { id, call_id, code, 3 more }` + The canonical name of the agent that produced this item. - - `id: string` + - `caller: optional object { type } or object { caller_id, type }` - The unique ID of the program item. + The execution context that produced this tool call. - - `call_id: string` + - `Direct object { type }` - The stable call ID of the program item. + - `type: "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`. - - `"program"` - - `agent: optional object { agent_name }` - - The agent that produced this item. + - `created_by: optional string` - - `agent_name: string` + The ID of the entity that created this tool call. - The canonical name of the agent that produced this item. + - `ShellCallOutput object { id, call_id, max_output_length, 6 more }` - - `ProgramOutput object { id, call_id, result, 3 more }` + The output of a shell tool call that was emitted. - `id: string` - The unique ID of the program output item. + The unique ID of the shell call output. Populated when this item is returned via API. - `call_id: string` - The call ID of the program item. + The unique ID of the shell tool call generated by the model. - - `result: string` + - `max_output_length: number` - The result produced by the program item. + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - `status: "completed" or "incomplete"` + - `output: array of object { outcome, stderr, stdout, created_by }` - The terminal status of the program output item. + An array of shell call output contents - - `"completed"` + - `outcome: object { type } or object { exit_code, type }` - - `"incomplete"` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - - `type: "program_output"` + - `Timeout object { type }` - The type of the item. Always `program_output`. + Indicates that the shell call exceeded its configured time limit. - - `"program_output"` + - `type: "timeout"` - - `agent: optional object { agent_name }` + The outcome type. Always `timeout`. - The agent that produced this item. + - `"timeout"` - - `agent_name: string` + - `Exit object { exit_code, type }` - The canonical name of the agent that produced this item. + Indicates that the shell commands finished and returned an exit code. - - `ToolSearchCall object { id, arguments, call_id, 5 more }` + - `exit_code: number` - - `id: string` + Exit code from the shell process. - The unique ID of the tool search call item. + - `type: "exit"` - - `arguments: unknown` + The outcome type. Always `exit`. - Arguments used for the tool search call. + - `"exit"` - - `call_id: string` + - `stderr: string` - The unique ID of the tool search call generated by the model. + The standard error output that was captured. - - `execution: "server" or "client"` + - `stdout: string` - Whether tool search was executed by the server or by the client. + The standard output that was captured. - - `"server"` + - `created_by: optional string` - - `"client"` + The identifier of the actor that created the item. - `status: "in_progress" or "completed" or "incomplete"` - The status of the tool search call item that was recorded. + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - `"in_progress"` @@ -139408,11 +136864,11 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"incomplete"` - - `type: "tool_search_call"` + - `type: "shell_call_output"` - The type of the item. Always `tool_search_call`. + The type of the shell call output. Always `shell_call_output`. - - `"tool_search_call"` + - `"shell_call_output"` - `agent: optional object { agent_name }` @@ -139422,3268 +136878,3190 @@ 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` - - 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"` + - `caller: optional object { type } or object { caller_id, type }` - - `"client"` + The execution context that produced this tool call. - - `status: "in_progress" or "completed" or "incomplete"` + - `Direct object { type }` - The status of the tool search output item that was recorded. + - `type: "direct"` - - `"in_progress"` + - `"direct"` - - `"completed"` + - `Program object { caller_id, type }` - - `"incomplete"` + - `caller_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 call ID of the program item that produced this tool call. - The loaded tool definitions returned by tool search. + - `type: "program"` - - `Function object { name, parameters, strict, 5 more }` + - `"program"` - 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). + - `created_by: optional string` - - `name: string` + The identifier of the actor that created the item. - The name of the function to call. + - `ApplyPatchCall object { id, call_id, operation, 5 more }` - - `parameters: map[unknown]` + A tool call that applies file diffs by creating, deleting, or updating files. - A JSON schema object describing the parameters of the function. + - `id: string` - - `strict: boolean` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - Whether strict parameter validation is enforced for this function tool. + - `call_id: string` - - `type: "function"` + The unique ID of the apply patch tool call generated by the model. - The type of the function tool. Always `function`. + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - - `"function"` + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `CreateFile object { diff, path, type }` - The tool invocation context(s). + Instruction describing how to create a file via the apply_patch tool. - - `"direct"` + - `diff: string` - - `"programmatic"` + Diff to apply. - - `defer_loading: optional boolean` + - `path: string` - Whether this function is deferred and loaded via tool search. + Path of the file to create. - - `description: optional string` + - `type: "create_file"` - A description of the function. Used by the model to determine whether or not to call the function. + Create a new file with the provided diff. - - `output_schema: optional map[unknown]` + - `"create_file"` - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `DeleteFile object { path, type }` - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + Instruction describing how to delete a file via the apply_patch tool. - 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). + - `path: string` - - `type: "file_search"` + Path of the file to delete. - The type of the file search tool. Always `file_search`. + - `type: "delete_file"` - - `"file_search"` + Delete the specified file. - - `vector_store_ids: array of string` + - `"delete_file"` - The IDs of the vector stores to search. + - `UpdateFile object { diff, path, type }` - - `filters: optional object { key, type, value } or object { filters, type }` + Instruction describing how to update a file via the apply_patch tool. - A filter to apply. + - `diff: string` - - `ComparisonFilter object { key, type, value }` + Diff to apply. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `path: string` - - `key: string` + Path of the file to update. - The key to compare against the value. + - `type: "update_file"` - - `type: "eq" or "ne" or "gt" or 5 more` + Update an existing file with the provided diff. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `"update_file"` - - `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 + - `status: "in_progress" or "completed"` - - `"eq"` + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `"ne"` + - `"in_progress"` - - `"gt"` + - `"completed"` - - `"gte"` + - `type: "apply_patch_call"` - - `"lt"` + The type of the item. Always `apply_patch_call`. - - `"lte"` + - `"apply_patch_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` + - `caller: optional object { type } or object { caller_id, type }` - - `number` + The execution context that produced this tool call. - - `boolean` + - `Direct object { type }` - - `array of string or number` + - `type: "direct"` - - `string` + - `"direct"` - - `number` + - `Program object { caller_id, type }` - - `CompoundFilter object { filters, type }` + - `caller_id: string` - Combine multiple filters using `and` or `or`. + The call ID of the program item that produced this tool call. - - `filters: array of object { key, type, value } or unknown` + - `type: "program"` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `"program"` - - `ComparisonFilter object { key, type, value }` + - `created_by: optional string` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The ID of the entity that created this tool call. - - `key: string` + - `ApplyPatchCallOutput object { id, call_id, status, 5 more }` - The key to compare against the value. + The output emitted by an apply patch tool call. - - `type: "eq" or "ne" or "gt" or 5 more` + - `id: string` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `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 + - `call_id: string` - - `"eq"` + The unique ID of the apply patch tool call generated by the model. - - `"ne"` + - `status: "completed" or "failed"` - - `"gt"` + The status of the apply patch tool call output. One of `completed` or `failed`. - - `"gte"` + - `"completed"` - - `"lt"` + - `"failed"` - - `"lte"` + - `type: "apply_patch_call_output"` - - `"in"` + The type of the item. Always `apply_patch_call_output`. - - `"nin"` + - `"apply_patch_call_output"` - - `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 produced this item. - - `string` + - `agent_name: string` - - `number` + The canonical name of the agent that produced this item. - - `boolean` + - `caller: optional object { type } or object { caller_id, type }` - - `array of string or number` + The execution context that produced this tool call. - - `string` + - `Direct object { type }` - - `number` + - `type: "direct"` - - `unknown` + - `"direct"` - - `type: "and" or "or"` + - `Program object { caller_id, type }` - Type of operation: `and` or `or`. + - `caller_id: string` - - `"and"` + The call ID of the program item that produced this tool call. - - `"or"` + - `type: "program"` - - `max_num_results: optional number` + - `"program"` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `created_by: optional string` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + The ID of the entity that created this tool call output. - Ranking options for search. + - `output: optional string` - - `hybrid_search: optional object { embedding_weight, text_weight }` + Optional textual output returned by the apply patch tool. - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `McpCall object { id, arguments, name, 7 more }` - - `embedding_weight: number` + An invocation of a tool on an MCP server. - The weight of the embedding in the reciprocal ranking fusion. + - `id: string` - - `text_weight: number` + The unique ID of the tool call. - The weight of the text in the reciprocal ranking fusion. + - `arguments: string` - - `ranker: optional "auto" or "default-2024-11-15"` + A JSON string of the arguments passed to the tool. - The ranker to use for the file search. + - `name: string` - - `"auto"` + The name of the tool that was run. - - `"default-2024-11-15"` + - `server_label: string` - - `score_threshold: optional number` + The label of the MCP server running the 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. + - `type: "mcp_call"` - - `Computer object { type }` + The type of the item. Always `mcp_call`. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `"mcp_call"` - - `type: "computer"` + - `agent: optional object { agent_name }` - The type of the computer tool. Always `computer`. + The agent that produced this item. - - `"computer"` + - `agent_name: string` - - `ComputerUsePreview object { display_height, display_width, environment, 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). + - `approval_request_id: optional string` - - `display_height: 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. - The height of the computer display. + - `error: optional string` - - `display_width: number` + The error from the tool call, if any. - The width of the computer display. + - `output: optional string` - - `environment: "windows" or "mac" or "linux" or 2 more` + The output from the tool call. - The type of computer environment to control. + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - - `"windows"` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `"mac"` + - `"in_progress"` - - `"linux"` + - `"completed"` - - `"ubuntu"` + - `"incomplete"` - - `"browser"` + - `"calling"` - - `type: "computer_use_preview"` + - `"failed"` - The type of the computer use tool. Always `computer_use_preview`. + - `McpListTools object { id, server_label, tools, 3 more }` - - `"computer_use_preview"` + A list of tools available on an MCP server. - - `WebSearch object { type, filters, search_context_size, user_location }` + - `id: string` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The unique ID of the list. - - `type: "web_search" or "web_search_2025_08_26"` + - `server_label: string` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + The label of the MCP server. - - `"web_search"` + - `tools: array of object { input_schema, name, annotations, description }` - - `"web_search_2025_08_26"` + The tools available on the server. - - `filters: optional object { allowed_domains }` + - `input_schema: unknown` - Filters for the search. + The JSON schema describing the tool's input. - - `allowed_domains: optional array of string` + - `name: string` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + The name of the tool. - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `annotations: optional unknown` - - `search_context_size: optional "low" or "medium" or "high"` + Additional annotations about the tool. - 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. + - `description: optional string` - - `"low"` + The description of the tool. - - `"medium"` + - `type: "mcp_list_tools"` - - `"high"` + The type of the item. Always `mcp_list_tools`. - - `user_location: optional object { city, country, region, 2 more }` + - `"mcp_list_tools"` - 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`. + - `error: optional string` - - `region: optional string` + Error message if the server could not list tools. - Free text input for the region of the user, e.g. `California`. + - `McpApprovalRequest object { id, arguments, name, 3 more }` - - `timezone: optional string` + A request for human approval of a tool invocation. - 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 approval request. - The type of location approximation. Always `approximate`. + - `arguments: string` - - `"approximate"` + A JSON string of arguments for the tool. - - `Mcp object { server_label, type, allowed_callers, 9 more }` + - `name: string` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + The name of the tool to run. - `server_label: string` - A label for this MCP server, used to identify it in tool calls. + The label of the MCP server making the request. - - `type: "mcp"` + - `type: "mcp_approval_request"` - The type of the MCP tool. Always `mcp`. + The type of the item. Always `mcp_approval_request`. - - `"mcp"` + - `"mcp_approval_request"` - - `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 }` + - `McpApprovalResponse object { id, approval_request_id, approve, 3 more }` - List of allowed tool names or a filter object. + A response to an MCP approval request. - - `McpAllowedTools = array of string` + - `id: string` - A string array of allowed tool names + The unique ID of the approval response - - `McpToolFilter object { read_only, tool_names }` + - `approval_request_id: string` - A filter object to specify which tools are allowed. + The ID of the approval request being answered. - - `read_only: optional boolean` + - `approve: 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 the request was approved. - - `tool_names: optional array of string` + - `type: "mcp_approval_response"` - List of allowed tool names. + The type of the item. Always `mcp_approval_response`. - - `authorization: optional string` + - `"mcp_approval_response"` - 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](https://platform.openai.com/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` + - `reason: optional string` - - `"connector_dropbox"` + Optional reason for the decision. - - `"connector_gmail"` + - `CustomToolCall object { call_id, input, name, 5 more }` - - `"connector_googlecalendar"` + A call to a custom tool created by the model. - - `"connector_googledrive"` + - `call_id: string` - - `"connector_microsoftteams"` + An identifier used to map this custom tool call to a tool call output. - - `"connector_outlookcalendar"` + - `input: string` - - `"connector_outlookemail"` + The input for the custom tool call generated by the model. - - `"connector_sharepoint"` + - `name: string` - - `defer_loading: optional boolean` + The name of the custom tool being called. - Whether this MCP tool is deferred and discovered via tool search. + - `type: "custom_tool_call"` - - `headers: optional map[string]` + The type of the custom tool call. Always `custom_tool_call`. - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `"custom_tool_call"` - - `require_approval: optional object { always, never } or "always" or "never"` + - `id: optional string` - Specify which of the MCP server's tools require approval. + The unique ID of the custom tool call in the OpenAI platform. - - `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` + - `caller: optional object { type } or 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. + The execution context that produced this tool call. - - `tool_names: optional array of string` + - `Direct object { type }` - List of allowed tool names. + - `type: "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. + - `"program"` - - `McpToolApprovalSetting = "always" or "never"` + - `namespace: optional string` - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + The namespace of the custom tool being called. - - `"always"` + - `CustomToolCallOutput object { id, call_id, output, 5 more }` - - `"never"` + - `id: string` - - `server_description: optional string` + The unique ID of the custom tool call output item. - Optional description of the MCP server, used to provide more context. + - `call_id: string` - - `server_url: optional string` + The call ID, used to map this custom tool call output to a custom tool call. - 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 custom tool 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 custom tool 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 custom 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. + - `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: "custom_tool_call_output"` - - `"1g"` + The type of the custom tool call output. Always `custom_tool_call_output`. - - `"4g"` + - `"custom_tool_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. +### Beta Response Output Item Added Event - - `type: "image_generation"` +- `BetaResponseOutputItemAddedEvent object { item, output_index, sequence_number, 2 more }` - The type of the image generation tool. Always `image_generation`. + Emitted when a new output item is added. - - `"image_generation"` + - `item: BetaResponseOutputItem` - - `action: optional "generate" or "edit" or "auto"` + The output item that was added. - Whether to generate a new image or edit an existing image. Default: `auto`. + - `BetaResponseOutputMessage object { id, content, role, 4 more }` - - `"generate"` + An output message from the model. - - `"edit"` + - `id: string` - - `"auto"` + The unique ID of the output message. - - `background: optional "transparent" or "opaque" or "auto"` + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + The content of the output message. - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + A text output from the model. - - `"transparent"` + - `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 }` - - `"opaque"` + The annotations of the text output. - - `"auto"` + - `FileCitation object { file_id, filename, index, type }` - - `input_fidelity: optional "high" or "low"` + A citation to a 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`. + - `file_id: string` - - `"high"` + The ID of the file. - - `"low"` + - `filename: string` - - `input_image_mask: optional object { file_id, image_url }` + The filename of the file cited. - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `index: number` - - `file_id: optional string` + The index of the file in the list of files. - File ID for the mask image. + - `type: "file_citation"` - - `image_url: optional string` + The type of the file citation. Always `file_citation`. - Base64-encoded mask image. + - `"file_citation"` - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `URLCitation object { end_index, start_index, title, 2 more }` - The image generation model to use. Default: `gpt-image-1`. + A citation for a web resource used to generate a model response. - - `string` + - `end_index: number` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + The index of the last character of the URL citation in the message. - The image generation model to use. Default: `gpt-image-1`. + - `start_index: number` - - `"gpt-image-1"` + The index of the first character of the URL citation in the message. - - `"gpt-image-1-mini"` + - `title: string` - - `"gpt-image-2"` + The title of the web resource. - - `"gpt-image-2-2026-04-21"` + - `type: "url_citation"` - - `"gpt-image-1.5"` + The type of the URL citation. Always `url_citation`. - - `"chatgpt-image-latest"` + - `"url_citation"` - - `moderation: optional "auto" or "low"` + - `url: string` - Moderation level for the generated image. Default: `auto`. + The URL of the web resource. - - `"auto"` + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - - `"low"` + A citation for a container file used to generate a model response. - - `output_compression: optional number` + - `container_id: string` - Compression level for the output image. Default: 100. + The ID of the container file. - - `output_format: optional "png" or "webp" or "jpeg"` + - `end_index: number` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + The index of the last character of the container file citation in the message. - - `"png"` + - `file_id: string` - - `"webp"` + The ID of the file. - - `"jpeg"` + - `filename: string` - - `partial_images: optional number` + The filename of the container file cited. - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `start_index: number` - - `quality: optional "low" or "medium" or "high" or "auto"` + The index of the first character of the container file citation in the message. - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `type: "container_file_citation"` - - `"low"` + The type of the container file citation. Always `container_file_citation`. - - `"medium"` + - `"container_file_citation"` - - `"high"` + - `FilePath object { file_id, index, type }` - - `"auto"` + A path to a file. - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `file_id: string` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + The ID of the file. - - `string` + - `index: number` - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + The index of the file in the list of files. - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `type: "file_path"` - - `"1024x1024"` + The type of the file path. Always `file_path`. - - `"1024x1536"` + - `"file_path"` - - `"1536x1024"` + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - - `"auto"` + - `token: string` - - `LocalShell object { type }` + - `bytes: array of number` - A tool that allows the model to execute shell commands in a local environment. + - `logprob: number` - - `type: "local_shell"` + - `top_logprobs: array of object { token, bytes, logprob }` - The type of the local shell tool. Always `local_shell`. + - `token: string` - - `"local_shell"` + - `bytes: array of number` - - `Shell object { type, allowed_callers, environment }` + - `logprob: number` - A tool that allows the model to execute shell commands. + - `text: string` - - `type: "shell"` + The text output from the model. - The type of the shell tool. Always `shell`. + - `type: "output_text"` - - `"shell"` + The type of the output text. Always `output_text`. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"output_text"` - The tool invocation context(s). + - `BetaResponseOutputRefusal object { refusal, type }` - - `"direct"` + A refusal from the model. - - `"programmatic"` + - `refusal: string` - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + The refusal explanation from the model. - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `type: "refusal"` - - `BetaLocalEnvironment object { type, skills }` + The type of the refusal. Always `refusal`. - - `BetaContainerReference object { container_id, type }` + - `"refusal"` - - `Custom object { name, type, allowed_callers, 3 more }` + - `role: "assistant"` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The role of the output message. Always `assistant`. - - `name: string` + - `"assistant"` - The name of the custom tool, used to identify it in tool calls. + - `status: "in_progress" or "completed" or "incomplete"` - - `type: "custom"` + 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 custom tool. Always `custom`. + - `"in_progress"` - - `"custom"` + - `"completed"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"incomplete"` - The tool invocation context(s). + - `type: "message"` - - `"direct"` + The type of the output message. Always `message`. - - `"programmatic"` + - `"message"` - - `defer_loading: optional boolean` + - `agent: optional object { agent_name }` - Whether this tool should be deferred and discovered via tool search. + The agent that produced this item. - - `description: optional string` + - `agent_name: string` - Optional description of the custom tool, used to provide more context. + The canonical name of the agent that produced this item. - - `format: optional object { type } or object { definition, syntax, type }` + - `phase: optional "commentary" or "final_answer"` - The input format for the custom tool. Default is unconstrained 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. - - `Text object { type }` + - `"commentary"` - Unconstrained free-form text. + - `"final_answer"` - - `type: "text"` + - `FileSearchCall object { id, queries, status, 3 more }` - Unconstrained text format. Always `text`. + The results of a file search tool call. See the + [file search guide](/docs/guides/tools-file-search) for more information. - - `"text"` + - `id: string` - - `Grammar object { definition, syntax, type }` + The unique ID of the file search tool call. - A grammar defined by the user. + - `queries: array of string` - - `definition: string` + The queries used to search for files. - The grammar definition. + - `status: "in_progress" or "searching" or "completed" or 2 more` - - `syntax: "lark" or "regex"` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - The syntax of the grammar definition. One of `lark` or `regex`. + - `"in_progress"` - - `"lark"` + - `"searching"` - - `"regex"` + - `"completed"` - - `type: "grammar"` + - `"incomplete"` - Grammar format. Always `grammar`. + - `"failed"` - - `"grammar"` + - `type: "file_search_call"` - - `Namespace object { description, name, tools, type }` + The type of the file search tool call. Always `file_search_call`. - Groups function/custom tools under a shared namespace. + - `"file_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 }` + - `results: optional array of object { attributes, file_id, filename, 2 more }` - The function/custom tools available inside this namespace. + The results of the file search tool call. - - `Function object { name, type, allowed_callers, 5 more }` + - `attributes: optional map[string or number or boolean]` - - `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. Keys are strings + with a maximum length of 64 characters. Values are strings with a maximum + length of 512 characters, booleans, or numbers. - - `type: "function"` + - `string` - - `"function"` + - `number` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `boolean` - The tool invocation context(s). + - `file_id: optional string` - - `"direct"` + The unique ID of the file. - - `"programmatic"` + - `filename: optional string` - - `defer_loading: optional boolean` + The name of the file. - Whether this function should be deferred and discovered via tool search. + - `score: optional number` - - `description: optional string` + The relevance score of the file - a value between 0 and 1. - - `output_schema: optional map[unknown]` + - `text: 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 text that was retrieved from the file. - - `parameters: optional unknown` + - `FunctionCall object { arguments, call_id, name, 6 more }` - - `strict: optional boolean` + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. - 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. + - `arguments: string` - - `Custom object { name, type, allowed_callers, 3 more }` + A JSON string of the arguments to pass to the function. + + - `call_id: string` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The unique ID of the function tool call generated by the model. - `name: string` - The name of the custom tool, used to identify it in tool calls. + The name of the function to run. - - `type: "custom"` + - `type: "function_call"` - The type of the custom tool. Always `custom`. + The type of the function tool call. Always `function_call`. - - `"custom"` + - `"function_call"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `id: optional string` - The tool invocation context(s). + The unique ID of the function tool 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` + - `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 }` + - `"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 }` + - `"program"` - A grammar defined by the user. + - `namespace: optional string` - - `definition: string` + The namespace of the function to run. - The grammar definition. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `syntax: "lark" or "regex"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The syntax of the grammar definition. One of `lark` or `regex`. + - `"in_progress"` - - `"lark"` + - `"completed"` - - `"regex"` + - `"incomplete"` - - `type: "grammar"` + - `FunctionCallOutput object { id, call_id, output, 5 more }` - Grammar format. Always `grammar`. + - `id: string` - - `"grammar"` + The unique ID of the function call tool output. - - `type: "namespace"` + - `call_id: string` - The type of the tool. Always `namespace`. + The unique ID of the function tool call generated by the model. - - `"namespace"` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `ToolSearch object { type, description, execution, parameters }` + The output from the function 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 function 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 function 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"` + - `text: string` - Whether tool search is executed by the server or by the client. + The text input to the model. - - `"server"` + - `type: "input_text"` - - `"client"` + The type of the input item. Always `input_text`. - - `parameters: optional unknown` + - `"input_text"` - Parameter schema for a client-executed tool search tool. + - `prompt_cache_breakpoint: optional object { mode }` - - `WebSearchPreview object { type, search_content_types, 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. - 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). + - `mode: "explicit"` - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + The breakpoint mode. Always `explicit`. - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `"explicit"` - - `"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"` + - `detail: "low" or "high" or "auto" or "original"` - - `"text"` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `"image"` + - `"low"` - - `search_context_size: optional "low" or "medium" or "high"` + - `"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. + - `"auto"` - - `"low"` + - `"original"` - - `"medium"` + - `type: "input_image"` - - `"high"` + The type of the input item. Always `input_image`. - - `user_location: optional object { type, city, country, 2 more }` + - `"input_image"` - The user's location. + - `file_id: optional string` - - `type: "approximate"` + The ID of the file to be sent to the model. - The type of location approximation. Always `approximate`. + - `image_url: optional string` - - `"approximate"` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `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`. + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `timezone: optional string` + A file input to the model. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `type: "input_file"` - - `ApplyPatch object { type, allowed_callers }` + The type of the input item. Always `input_file`. - Allows the assistant to create, delete, or update files using unified diffs. + - `"input_file"` - - `type: "apply_patch"` + - `detail: optional "auto" or "low" or "high"` - The type of the tool. Always `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`. - - `"apply_patch"` + - `"auto"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"low"` - The tool invocation context(s). + - `"high"` - - `"direct"` + - `file_data: optional string` - - `"programmatic"` + The content of the file to be sent to the model. - - `type: "tool_search_output"` + - `file_id: optional string` - The type of the item. Always `tool_search_output`. + The ID of the file to be sent to the model. - - `"tool_search_output"` + - `file_url: optional string` - - `agent: optional object { agent_name }` + The URL of the file to be sent to the model. - The agent that produced this item. + - `filename: optional string` - - `agent_name: string` + The name of the file to be sent to the model. - The canonical name of the agent that produced this item. + - `prompt_cache_breakpoint: optional object { mode }` - - `created_by: 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 identifier of the actor that created the item. + - `mode: "explicit"` - - `AdditionalTools object { id, role, tools, 2 more }` + The breakpoint mode. Always `explicit`. - - `id: string` + - `"explicit"` - The unique ID of the additional tools item. + - `status: "in_progress" or "completed" or "incomplete"` - - `role: "unknown" or "user" or "assistant" or 5 more` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The role that provided the additional tools. + - `"in_progress"` - - `"unknown"` + - `"completed"` - - `"user"` + - `"incomplete"` - - `"assistant"` + - `type: "function_call_output"` - - `"system"` + The type of the function tool call output. Always `function_call_output`. - - `"critic"` + - `"function_call_output"` - - `"discriminator"` + - `agent: optional object { agent_name }` - - `"developer"` + The agent that produced this item. - - `"tool"` + - `agent_name: 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 canonical name of the agent that produced this item. - The additional tool definitions made available at this item. + - `caller: optional object { type } or object { caller_id, type }` - - `Function object { name, parameters, strict, 5 more }` + The execution context that produced this 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). + - `Direct object { type }` - - `name: string` + - `type: "direct"` - The name of the function to call. + The caller type. Always `direct`. - - `parameters: map[unknown]` + - `"direct"` - A JSON schema object describing the parameters of the function. + - `Program object { caller_id, type }` - - `strict: boolean` + - `caller_id: string` - Whether strict parameter validation is enforced for this function tool. + The call ID of the program item that produced this tool call. - - `type: "function"` + - `type: "program"` - The type of the function tool. Always `function`. + The caller type. Always `program`. - - `"function"` + - `"program"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `created_by: optional string` - The tool invocation context(s). + The identifier of the actor that created the item. - - `"direct"` + - `AgentMessage object { id, author, content, 3 more }` - - `"programmatic"` + - `id: string` - - `defer_loading: optional boolean` + The unique ID of the agent message. - Whether this function is deferred and loaded via tool search. + - `author: string` - - `description: optional string` + The sending agent identity. - A description of the function. Used by the model to determine whether or not to call the function. + - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` - - `output_schema: optional map[unknown]` + Encrypted content sent between agents. - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + A text input 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). + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - - `type: "file_search"` + A text output from the model. - The type of the file search tool. Always `file_search`. + - `Text object { text, type }` - - `"file_search"` + A text content. - - `vector_store_ids: array of string` + - `text: string` - The IDs of the vector stores to search. + - `type: "text"` - - `filters: optional object { key, type, value } or object { filters, type }` + - `"text"` - A filter to apply. + - `SummaryText object { text, type }` - - `ComparisonFilter object { key, type, value }` + A summary text from the model. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `text: string` - - `key: string` + A summary of the reasoning output from the model so far. - The key to compare against the value. + - `type: "summary_text"` - - `type: "eq" or "ne" or "gt" or 5 more` + The type of the object. Always `summary_text`. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `"summary_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 + - `ReasoningText object { text, type }` - - `"eq"` + Reasoning text from the model. - - `"ne"` + - `text: string` - - `"gt"` + The reasoning text from the model. - - `"gte"` + - `type: "reasoning_text"` - - `"lt"` + The type of the reasoning text. Always `reasoning_text`. - - `"lte"` + - `"reasoning_text"` - - `"in"` + - `BetaResponseOutputRefusal object { refusal, type }` - - `"nin"` + A refusal from the model. - - `value: string or number or boolean or array of string or number` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - The value to compare against the attribute key; supports string, number, or boolean types. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `string` + - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` - - `number` + A screenshot of a computer. - - `boolean` + - `detail: "low" or "high" or "auto" or "original"` - - `array of string or number` + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `string` + - `"low"` - - `number` + - `"high"` - - `CompoundFilter object { filters, type }` + - `"auto"` - Combine multiple filters using `and` or `or`. + - `"original"` - - `filters: array of object { key, type, value } or unknown` + - `file_id: string` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + The identifier of an uploaded file that contains the screenshot. - - `ComparisonFilter object { key, type, value }` + - `image_url: string` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The URL of the screenshot image. - - `key: string` + - `type: "computer_screenshot"` - The key to compare against the value. + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `type: "eq" or "ne" or "gt" or 5 more` + - `"computer_screenshot"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `prompt_cache_breakpoint: optional object { mode }` - - `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 + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `"eq"` + - `mode: "explicit"` - - `"ne"` + The breakpoint mode. Always `explicit`. - - `"gt"` + - `"explicit"` - - `"gte"` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `"lt"` + A file input to the model. - - `"lte"` + - `EncryptedContent object { encrypted_content, type }` - - `"in"` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `"nin"` + - `encrypted_content: string` - - `value: string or number or boolean or array of string or number` + Opaque encrypted content. - The value to compare against the attribute key; supports string, number, or boolean types. + - `type: "encrypted_content"` - - `string` + The type of the input item. Always `encrypted_content`. - - `number` + - `"encrypted_content"` - - `boolean` + - `recipient: string` - - `array of string or number` + The destination agent identity. - - `string` + - `type: "agent_message"` - - `number` + The type of the item. Always `agent_message`. - - `unknown` + - `"agent_message"` - - `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` + - `MultiAgentCall object { id, action, arguments, 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 the multi-agent call item. - Ranking options for search. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `hybrid_search: optional object { embedding_weight, text_weight }` + The multi-agent action to execute. - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `"spawn_agent"` - - `embedding_weight: number` + - `"interrupt_agent"` - The weight of the embedding in the reciprocal ranking fusion. + - `"list_agents"` - - `text_weight: number` + - `"send_message"` - The weight of the text in the reciprocal ranking fusion. + - `"followup_task"` - - `ranker: optional "auto" or "default-2024-11-15"` + - `"wait_agent"` - The ranker to use for the file search. + - `arguments: string` - - `"auto"` + The JSON string of arguments generated for the action. - - `"default-2024-11-15"` + - `call_id: string` - - `score_threshold: optional number` + The unique ID linking this call to its output. - 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: "multi_agent_call"` - - `Computer object { type }` + The type of the multi-agent call. Always `multi_agent_call`. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `"multi_agent_call"` - - `type: "computer"` + - `agent: optional object { agent_name }` - The type of the computer tool. Always `computer`. + The agent that produced this item. - - `"computer"` + - `agent_name: string` - - `ComputerUsePreview object { display_height, display_width, environment, 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). + - `MultiAgentCallOutput object { id, action, call_id, 3 more }` - - `display_height: number` + - `id: string` - The height of the computer display. + The unique ID of the multi-agent call output item. - - `display_width: number` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - The width of the computer display. + The multi-agent action that produced this result. - - `environment: "windows" or "mac" or "linux" or 2 more` + - `"spawn_agent"` - The type of computer environment to control. + - `"interrupt_agent"` - - `"windows"` + - `"list_agents"` - - `"mac"` + - `"send_message"` - - `"linux"` + - `"followup_task"` - - `"ubuntu"` + - `"wait_agent"` - - `"browser"` + - `call_id: string` - - `type: "computer_use_preview"` + The unique ID of the multi-agent call. - The type of the computer use tool. Always `computer_use_preview`. + - `output: array of BetaResponseOutputText` - - `"computer_use_preview"` + Text output returned by the multi-agent action. - - `WebSearch object { type, filters, search_context_size, user_location }` + - `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 }` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The annotations of the text output. - - `type: "web_search" or "web_search_2025_08_26"` + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `text: string` - - `"web_search"` + The text output from the model. - - `"web_search_2025_08_26"` + - `type: "output_text"` - - `filters: optional object { allowed_domains }` + The type of the output text. Always `output_text`. - Filters for the search. + - `type: "multi_agent_call_output"` - - `allowed_domains: optional array of string` + The type of the multi-agent result. Always `multi_agent_call_output`. - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `"multi_agent_call_output"` - 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"` + - `WebSearchCall object { id, action, status, 2 more }` - - `"high"` + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. - - `user_location: optional object { city, country, region, 2 more }` + - `id: string` - The approximate location of the user. + The unique ID of the web search tool call. - - `city: optional string` + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - Free text input for the city of the user, e.g. `San Francisco`. + 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). - - `country: optional string` + - `Search object { type, queries, query, sources }` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + Action type "search" - Performs a web search query. - - `region: optional string` + - `type: "search"` - Free text input for the region of the user, e.g. `California`. + The action type. - - `timezone: optional string` + - `"search"` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `queries: optional array of string` - - `type: optional "approximate"` + The search queries. - The type of location approximation. Always `approximate`. + - `query: optional string` - - `"approximate"` + The search query. - - `Mcp object { server_label, type, allowed_callers, 9 more }` + - `sources: optional array of object { type, url }` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + The sources used in the search. - - `server_label: string` + - `type: "url"` - A label for this MCP server, used to identify it in tool calls. + The type of source. Always `url`. - - `type: "mcp"` + - `"url"` - The type of the MCP tool. Always `mcp`. + - `url: string` - - `"mcp"` + 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. - - `allowed_tools: optional array of string or object { read_only, tool_names }` + - `"open_page"` - List of allowed tool names or a filter object. + - `url: optional string` - - `McpAllowedTools = array of string` + The URL opened by the model. - A string array of allowed tool names + - `FindInPage object { pattern, type, url }` - - `McpToolFilter 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"` - - `authorization: optional string` + - `url: string` - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. + The URL of the page searched for the pattern. - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + - `status: "in_progress" or "searching" or "completed" or "failed"` - 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + The status of the web search tool call. - Currently supported `connector_id` values are: + - `"in_progress"` - - 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` + - `"searching"` - - `"connector_dropbox"` + - `"completed"` - - `"connector_gmail"` + - `"failed"` - - `"connector_googlecalendar"` + - `type: "web_search_call"` - - `"connector_googledrive"` + The type of the web search tool call. Always `web_search_call`. - - `"connector_microsoftteams"` + - `"web_search_call"` - - `"connector_outlookcalendar"` + - `agent: optional object { agent_name }` - - `"connector_outlookemail"` + The agent that produced this item. - - `"connector_sharepoint"` + - `agent_name: string` - - `defer_loading: optional boolean` + The canonical name of the agent that produced this item. - Whether this MCP tool is deferred and discovered via tool search. + - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` - - `headers: optional map[string]` + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - 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 unique ID of the computer call. - Specify which of the MCP server's tools require approval. + - `call_id: string` - - `McpToolApprovalFilter object { always, never }` + An identifier used when responding to the tool call with 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. + - `pending_safety_checks: array of object { id, code, message }` - - `always: optional object { read_only, tool_names }` + The pending safety checks for the computer call. - A filter object to specify which tools are allowed. + - `id: string` - - `read_only: optional boolean` + The ID of the pending safety check. - 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: optional string` - - `tool_names: optional array of string` + The type of the pending safety check. - List of allowed tool names. + - `message: optional string` - - `never: optional object { read_only, tool_names }` + Details about the pending safety check. - A filter object to specify which tools are allowed. + - `status: "in_progress" or "completed" or "incomplete"` - - `read_only: optional boolean` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `"in_progress"` - - `tool_names: optional array of string` + - `"completed"` - List of allowed tool names. + - `"incomplete"` - - `McpToolApprovalSetting = "always" or "never"` + - `type: "computer_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 computer call. Always `computer_call`. - - `"always"` + - `"computer_call"` - - `"never"` + - `action: optional BetaComputerAction` - - `server_description: optional string` + A click action. - Optional description of the MCP server, used to provide more context. + - `Click object { button, type, x, 2 more }` - - `server_url: optional string` + A click action. - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `button: "left" or "right" or "wheel" or 2 more` - - `tunnel_id: optional string` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - 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. + - `"left"` - - `CodeInterpreter object { container, type, allowed_callers }` + - `"right"` - A tool that runs Python code to help generate a response to a prompt. + - `"wheel"` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + - `"back"` - 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. + - `"forward"` - - `string` + - `type: "click"` - The container ID. + Specifies the event type. For a click action, this property is always `click`. - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + - `"click"` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `x: number` - - `type: "auto"` + The x-coordinate where the click occurred. - Always `auto`. + - `y: number` - - `"auto"` + The y-coordinate where the click occurred. - - `file_ids: optional array of string` + - `keys: optional array of string` - An optional list of uploaded files to make available to your code. + The keys being held while clicking. - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `DoubleClick object { keys, type, x, y }` - The memory limit for the code interpreter container. + A double click action. - - `"1g"` + - `keys: array of string` - - `"4g"` + The keys being held while double-clicking. - - `"16g"` + - `type: "double_click"` - - `"64g"` + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `"double_click"` - Network access policy for the container. + - `x: number` - - `BetaContainerNetworkPolicyDisabled object { type }` + The x-coordinate where the double click occurred. - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `y: number` - - `type: "code_interpreter"` + The y-coordinate where the double click occurred. - The type of the code interpreter tool. Always `code_interpreter`. + - `Drag object { path, type, keys }` - - `"code_interpreter"` + A drag action. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `path: array of object { x, y }` - The tool invocation context(s). + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `"direct"` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `"programmatic"` + - `x: number` - - `ProgrammaticToolCalling object { type }` + The x-coordinate. - - `type: "programmatic_tool_calling"` + - `y: number` - The type of the tool. Always `programmatic_tool_calling`. + The y-coordinate. - - `"programmatic_tool_calling"` + - `type: "drag"` - - `ImageGeneration object { type, action, background, 9 more }` + Specifies the event type. For a drag action, this property is always set to `drag`. - A tool that generates images using the GPT image models. + - `"drag"` - - `type: "image_generation"` + - `keys: optional array of string` - The type of the image generation tool. Always `image_generation`. + The keys being held while dragging the mouse. - - `"image_generation"` + - `Keypress object { keys, type }` - - `action: optional "generate" or "edit" or "auto"` + A collection of keypresses the model would like to perform. - Whether to generate a new image or edit an existing image. Default: `auto`. + - `keys: array of string` - - `"generate"` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `"edit"` + - `type: "keypress"` - - `"auto"` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `background: optional "transparent" or "opaque" or "auto"` + - `"keypress"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + - `Move object { type, x, y, keys }` - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + A mouse move action. - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `type: "move"` - - `"transparent"` + Specifies the event type. For a move action, this property is always set to `move`. - - `"opaque"` + - `"move"` - - `"auto"` + - `x: number` - - `input_fidelity: optional "high" or "low"` + The x-coordinate to move to. - 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 to move to. - - `"low"` + - `keys: optional array of string` - - `input_image_mask: optional object { file_id, image_url }` + The keys being held while moving the mouse. - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `Screenshot object { type }` - - `file_id: optional string` + A screenshot action. - File ID for the mask image. + - `type: "screenshot"` - - `image_url: optional string` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - Base64-encoded mask image. + - `"screenshot"` - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - The image generation model to use. Default: `gpt-image-1`. + A scroll action. - - `string` + - `scroll_x: number` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + The horizontal scroll distance. - The image generation model to use. Default: `gpt-image-1`. + - `scroll_y: number` - - `"gpt-image-1"` + The vertical scroll distance. - - `"gpt-image-1-mini"` + - `type: "scroll"` - - `"gpt-image-2"` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `"gpt-image-2-2026-04-21"` + - `"scroll"` - - `"gpt-image-1.5"` + - `x: number` - - `"chatgpt-image-latest"` + The x-coordinate where the scroll occurred. - - `moderation: optional "auto" or "low"` + - `y: number` - Moderation level for the generated image. Default: `auto`. + The y-coordinate where the scroll occurred. - - `"auto"` + - `keys: optional array of string` - - `"low"` + The keys being held while scrolling. - - `output_compression: optional number` + - `Type object { text, type }` - Compression level for the output image. Default: 100. + An action to type in text. - - `output_format: optional "png" or "webp" or "jpeg"` + - `text: string` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + The text to type. - - `"png"` + - `type: "type"` - - `"webp"` + Specifies the event type. For a type action, this property is always set to `type`. - - `"jpeg"` + - `"type"` - - `partial_images: optional number` + - `Wait object { type }` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + A wait action. - - `quality: optional "low" or "medium" or "high" or "auto"` + - `type: "wait"` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + Specifies the event type. For a wait action, this property is always set to `wait`. - - `"low"` + - `"wait"` - - `"medium"` + - `actions: optional BetaComputerActionList` - - `"high"` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `"auto"` + - `Click object { button, type, x, 2 more }` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + A click 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`. + - `DoubleClick object { keys, type, x, y }` - - `string` + A double click action. - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `Drag object { path, type, 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 drag action. - - `"1024x1024"` + - `Keypress object { keys, type }` - - `"1024x1536"` + A collection of keypresses the model would like to perform. - - `"1536x1024"` + - `Move object { type, x, y, keys }` - - `"auto"` + A mouse move action. - - `LocalShell object { type }` + - `Screenshot object { type }` - A tool that allows the model to execute shell commands in a local environment. + A screenshot action. - - `type: "local_shell"` + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - The type of the local shell tool. Always `local_shell`. + A scroll action. - - `"local_shell"` + - `Type object { text, type }` - - `Shell object { type, allowed_callers, environment }` + An action to type in text. - A tool that allows the model to execute shell commands. + - `Wait object { type }` - - `type: "shell"` + A wait action. - The type of the shell tool. Always `shell`. + - `agent: optional object { agent_name }` - - `"shell"` + 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"` + - `ComputerCallOutput object { id, call_id, output, 5 more }` - - `"programmatic"` + - `id: string` - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + The unique ID of the computer call tool output. - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `call_id: string` - - `BetaLocalEnvironment object { type, skills }` + The ID of the computer tool call that produced the output. - - `BetaContainerReference object { container_id, type }` + - `output: BetaResponseComputerToolCallOutputScreenshot` - - `Custom object { name, type, allowed_callers, 3 more }` + A computer screenshot image used with the computer use tool. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `type: "computer_screenshot"` - - `name: string` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - The name of the custom tool, used to identify it in tool calls. + - `"computer_screenshot"` - - `type: "custom"` + - `file_id: optional string` - The type of the custom tool. Always `custom`. + The identifier of an uploaded file that contains the screenshot. - - `"custom"` + - `image_url: optional string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The URL of the screenshot image. - The tool invocation context(s). + - `status: "completed" or "incomplete" or "failed" or "in_progress"` - - `"direct"` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `"programmatic"` + - `"completed"` - - `defer_loading: optional boolean` + - `"incomplete"` - Whether this tool should be deferred and discovered via tool search. + - `"failed"` - - `description: optional string` + - `"in_progress"` - Optional description of the custom tool, used to provide more context. + - `type: "computer_call_output"` - - `format: optional object { type } or object { definition, syntax, type }` + The type of the computer tool call output. Always `computer_call_output`. - The input format for the custom tool. Default is unconstrained text. + - `"computer_call_output"` - - `Text object { type }` + - `acknowledged_safety_checks: optional array of object { id, code, message }` - Unconstrained free-form text. + The safety checks reported by the API that have been acknowledged by the + developer. - - `type: "text"` + - `id: string` - Unconstrained text format. Always `text`. + The ID of the pending safety check. - - `"text"` + - `code: optional string` - - `Grammar object { definition, syntax, type }` + The type of the pending safety check. - A grammar defined by the user. + - `message: optional string` - - `definition: string` + Details about the pending safety check. - 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"` + - `created_by: optional string` - - `type: "grammar"` + The identifier of the actor that created the item. - Grammar format. Always `grammar`. + - `Reasoning object { id, summary, type, 4 more }` - - `"grammar"` + 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). - - `Namespace object { description, name, tools, type }` + - `id: string` - Groups function/custom tools under a shared namespace. + The unique identifier of the reasoning content. - - `description: string` + - `summary: array of object { text, type }` - A description of the namespace shown to the model. + Reasoning summary content. - - `name: string` + - `text: string` - The namespace name used in tool calls (for example, `crm`). + A summary of the reasoning output from the model so far. - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + - `type: "summary_text"` - The function/custom tools available inside this namespace. + The type of the object. Always `summary_text`. - - `Function object { name, type, allowed_callers, 5 more }` + - `"summary_text"` - - `name: string` + - `type: "reasoning"` - - `type: "function"` + The type of the object. Always `reasoning`. - - `"function"` + - `"reasoning"` - - `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` + - `content: optional array of object { text, type }` - Whether this function should be deferred and discovered via tool search. + Reasoning text content. - - `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. + - `encrypted_content: optional string` - - `Custom object { name, type, allowed_callers, 3 more }` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `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, used to identify it in tool calls. + - `"in_progress"` - - `type: "custom"` + - `"completed"` - The type of the custom tool. Always `custom`. + - `"incomplete"` - - `"custom"` + - `Program object { id, call_id, code, 3 more }` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `id: string` - The tool invocation context(s). + The unique ID of the program item. - - `"direct"` + - `call_id: string` - - `"programmatic"` + The stable call ID of the program item. - - `defer_loading: optional boolean` + - `code: string` - Whether this tool should be deferred and discovered via tool search. + The JavaScript source executed by programmatic tool calling. - - `description: optional string` + - `fingerprint: string` - Optional description of the custom tool, used to provide more context. + Opaque program replay fingerprint that must be round-tripped. - - `format: optional object { type } or object { definition, syntax, type }` + - `type: "program"` - The input format for the custom tool. Default is unconstrained text. + The type of the item. Always `program`. - - `Text object { type }` + - `"program"` - 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 }` + - `ProgramOutput object { id, call_id, result, 3 more }` - A grammar defined by the user. + - `id: string` - - `definition: string` + The unique ID of the program output item. - The grammar definition. + - `call_id: string` - - `syntax: "lark" or "regex"` + The call ID of the program item. - The syntax of the grammar definition. One of `lark` or `regex`. + - `result: string` - - `"lark"` + The result produced by the program item. - - `"regex"` + - `status: "completed" or "incomplete"` - - `type: "grammar"` + The terminal status of the program output item. - Grammar format. Always `grammar`. + - `"completed"` - - `"grammar"` + - `"incomplete"` - - `type: "namespace"` + - `type: "program_output"` - The type of the tool. Always `namespace`. + The type of the item. Always `program_output`. - - `"namespace"` + - `"program_output"` - - `ToolSearch object { type, description, execution, parameters }` + - `agent: optional object { agent_name }` - Hosted or BYOT tool search configuration for deferred tools. + The agent that produced this item. - - `type: "tool_search"` + - `agent_name: string` - The type of the tool. Always `tool_search`. + The canonical name of the agent that produced this item. - - `"tool_search"` + - `ToolSearchCall object { id, arguments, call_id, 5 more }` - - `description: optional string` + - `id: string` - Description shown to the model for a client-executed tool search tool. + The unique ID of the tool search call item. - - `execution: optional "server" or "client"` + - `arguments: unknown` - Whether tool search is executed by the server or by the client. + Arguments used for the tool search call. - - `"server"` + - `call_id: string` - - `"client"` + The unique ID of the tool search call generated by the model. - - `parameters: optional unknown` + - `execution: "server" or "client"` - Parameter schema for a client-executed tool search tool. + Whether tool search was executed by the server or by the client. - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + - `"server"` - 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). + - `"client"` - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `status: "in_progress" or "completed" or "incomplete"` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + The status of the tool search call item that was recorded. - - `"web_search_preview"` + - `"in_progress"` - - `"web_search_preview_2025_03_11"` + - `"completed"` - - `search_content_types: optional array of "text" or "image"` + - `"incomplete"` - - `"text"` + - `type: "tool_search_call"` - - `"image"` + The type of the item. Always `tool_search_call`. - - `search_context_size: optional "low" or "medium" or "high"` + - `"tool_search_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 }` + - `created_by: optional string` - The user's location. + The identifier of the actor that created the item. - - `type: "approximate"` + - `ToolSearchOutput object { id, call_id, execution, 5 more }` - The type of location approximation. Always `approximate`. + - `id: string` - - `"approximate"` + The unique ID of the tool search output item. - - `city: optional string` + - `call_id: string` - Free text input for the city of the user, e.g. `San Francisco`. + The unique ID of the tool search call generated by the model. - - `country: optional string` + - `execution: "server" or "client"` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + Whether tool search was executed by the server or by the client. - - `region: optional string` + - `"server"` - Free text input for the region of the user, e.g. `California`. + - `"client"` - - `timezone: optional string` + - `status: "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 tool search output item that was recorded. - - `ApplyPatch object { type, allowed_callers }` + - `"in_progress"` - Allows the assistant to create, delete, or update files using unified diffs. + - `"completed"` - - `type: "apply_patch"` + - `"incomplete"` - The type of the tool. Always `apply_patch`. + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - - `"apply_patch"` + The loaded tool definitions returned by tool search. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `Function object { name, parameters, strict, 5 more }` - The tool invocation context(s). + 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). - - `"direct"` + - `name: string` - - `"programmatic"` + The name of the function to call. - - `type: "additional_tools"` + - `parameters: map[unknown]` - The type of the item. Always `additional_tools`. + A JSON schema object describing the parameters of the function. - - `"additional_tools"` + - `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"` - - `Compaction object { id, encrypted_content, type, 2 more }` + - `allowed_callers: optional array of "direct" or "programmatic"` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + The tool invocation context(s). - - `id: string` + - `"direct"` - The unique ID of the compaction item. + - `"programmatic"` - - `encrypted_content: string` + - `defer_loading: optional boolean` - The encrypted content that was produced by compaction. + Whether this function is deferred and loaded via tool search. - - `type: "compaction"` + - `description: optional string` - The type of the item. Always `compaction`. + A description of the function. Used by the model to determine whether or not to call the function. - - `"compaction"` + - `output_schema: optional map[unknown]` - - `agent: optional object { agent_name }` + A JSON schema object describing the JSON value encoded in string outputs for this function. - The agent that produced this item. + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - - `agent_name: 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 canonical name of the agent that produced this item. + - `type: "file_search"` - - `created_by: optional string` + The type of the file search tool. Always `file_search`. - The identifier of the actor that created the item. + - `"file_search"` - - `ImageGenerationCall object { id, result, status, 2 more }` + - `vector_store_ids: array of string` - An image generation request made by the model. + 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 image generation call. + A filter to apply. - - `result: string` + - `ComparisonFilter object { key, type, value }` - The generated image encoded in base64. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `status: "in_progress" or "completed" or "generating" or "failed"` + - `key: string` - The status of the image generation call. + 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`. - - `"generating"` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `"failed"` + - `"eq"` - - `type: "image_generation_call"` + - `"ne"` - The type of the image generation call. Always `image_generation_call`. + - `"gt"` - - `"image_generation_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"` - - `CodeInterpreterCall object { id, code, container_id, 4 more }` + - `value: string or number or boolean or array of string or number` - A tool call to run code. + The value to compare against the attribute key; supports string, number, or boolean types. - - `id: string` + - `string` - The unique ID of the code interpreter tool call. + - `number` - - `code: string` + - `boolean` - The code to run, or null if not available. + - `array of string or number` - - `container_id: string` + - `string` - The ID of the container used to run the code. + - `number` - - `outputs: array of object { logs, type } or object { type, url }` + - `CompoundFilter object { filters, type }` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + Combine multiple filters using `and` or `or`. - - `Logs object { logs, type }` + - `filters: array of object { key, type, value } or unknown` - The logs output from the code interpreter. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `logs: string` + - `ComparisonFilter object { key, type, value }` - The logs output from the code interpreter. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `type: "logs"` + - `key: string` - The type of the output. Always `logs`. + The key to compare against the value. - - `"logs"` + - `type: "eq" or "ne" or "gt" or 5 more` - - `Image object { type, url }` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The image output from the code interpreter. + - `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: "image"` + - `"eq"` - The type of the output. Always `image`. + - `"ne"` - - `"image"` + - `"gt"` - - `url: string` + - `"gte"` - The URL of the image output from the code interpreter. + - `"lt"` - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + - `"lte"` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `"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. - - `"interpreting"` + - `string` - - `"failed"` + - `number` - - `type: "code_interpreter_call"` + - `boolean` - The type of the code interpreter tool call. Always `code_interpreter_call`. + - `array of string or number` - - `"code_interpreter_call"` + - `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`. - - `LocalShellCall object { id, action, call_id, 3 more }` + - `"and"` - A tool call to run a command on the local shell. + - `"or"` - - `id: string` + - `max_num_results: optional number` - The unique ID of the local shell call. + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `action: object { command, env, type, 3 more }` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - Execute a shell command on the server. + Ranking options for search. - - `command: array of string` + - `hybrid_search: optional object { embedding_weight, text_weight }` - The command to run. + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `env: map[string]` + - `embedding_weight: number` - Environment variables to set for the command. + The weight of the embedding in the reciprocal ranking fusion. - - `type: "exec"` + - `text_weight: number` - The type of the local shell action. Always `exec`. + The weight of the text in the reciprocal ranking fusion. - - `"exec"` + - `ranker: optional "auto" or "default-2024-11-15"` - - `timeout_ms: optional number` + The ranker to use for the file search. - Optional timeout in milliseconds for the command. + - `"auto"` - - `user: optional string` + - `"default-2024-11-15"` - Optional user to run the command as. + - `score_threshold: optional number` - - `working_directory: optional string` + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - Optional working directory to run the command in. + - `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 local shell tool call generated by the model. + - `type: "computer"` - - `status: "in_progress" or "completed" or "incomplete"` + The type of the computer tool. Always `computer`. - The status of the local shell call. + - `"computer"` - - `"in_progress"` + - `ComputerUsePreview object { display_height, display_width, environment, 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"` + - `display_height: number` - - `type: "local_shell_call"` + The height of the computer display. - The type of the local shell call. Always `local_shell_call`. + - `display_width: number` - - `"local_shell_call"` + The width of the computer display. - - `agent: optional object { agent_name }` + - `environment: "windows" or "mac" or "linux" or 2 more` - The agent that produced this item. + The type of computer environment to control. - - `agent_name: string` + - `"windows"` - The canonical name of the agent that produced this item. + - `"mac"` - - `LocalShellCallOutput object { id, output, type, 2 more }` + - `"linux"` - The output of a local shell tool call. + - `"ubuntu"` - - `id: string` + - `"browser"` - The unique ID of the local shell tool call generated by the model. + - `type: "computer_use_preview"` - - `output: string` + The type of the computer use tool. Always `computer_use_preview`. - A JSON string of the output of the local shell tool call. + - `"computer_use_preview"` - - `type: "local_shell_call_output"` + - `WebSearch object { type, filters, search_context_size, user_location }` - The type of the local shell tool call output. Always `local_shell_call_output`. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - - `"local_shell_call_output"` + - `type: "web_search" or "web_search_2025_08_26"` - - `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 produced this item. + - `"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 }` - - `status: optional "in_progress" or "completed" or "incomplete"` + Filters for the search. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `allowed_domains: optional array of string` - - `"in_progress"` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `"completed"` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `"incomplete"` + - `search_context_size: optional "low" or "medium" or "high"` - - `ShellCall object { id, action, call_id, 6 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. - A tool call that executes one or more shell commands in a managed environment. + - `"low"` - - `id: string` + - `"medium"` - The unique ID of the shell tool call. Populated when this item is returned via API. + - `"high"` - - `action: object { commands, max_output_length, timeout_ms }` + - `user_location: optional object { city, country, region, 2 more }` - The shell commands and limits that describe how to run the tool call. + The approximate location of the user. - - `commands: array of string` + - `city: optional string` - - `max_output_length: number` + Free text input for the city of the user, e.g. `San Francisco`. - Optional maximum number of characters to return from each command. + - `country: optional string` - - `timeout_ms: number` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - Optional timeout in milliseconds for the commands. + - `region: optional string` - - `call_id: string` + Free text input for the region of the user, e.g. `California`. - The unique ID of the shell tool call generated by the model. + - `timezone: optional string` - - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - Represents the use of a local environment to perform shell actions. + - `type: optional "approximate"` - - `BetaResponseLocalEnvironment object { type }` + The type of location approximation. Always `approximate`. - Represents the use of a local environment to perform shell actions. + - `"approximate"` - - `type: "local"` + - `Mcp object { server_label, type, allowed_callers, 9 more }` - The environment type. Always `local`. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - - `"local"` + - `server_label: string` - - `BetaResponseContainerReference object { container_id, type }` + A label for this MCP server, used to identify it in tool calls. - Represents a container created with /v1/containers. + - `type: "mcp"` - - `container_id: string` + The type of the MCP tool. Always `mcp`. - - `type: "container_reference"` + - `"mcp"` - The environment type. Always `container_reference`. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"container_reference"` + The tool invocation context(s). - - `status: "in_progress" or "completed" or "incomplete"` + - `"direct"` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `"programmatic"` - - `"in_progress"` + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `"completed"` + List of allowed tool names or a filter object. - - `"incomplete"` + - `McpAllowedTools = array of string` - - `type: "shell_call"` + A string array of allowed tool names - The type of the item. Always `shell_call`. + - `McpToolFilter object { read_only, tool_names }` - - `"shell_call"` + A filter object to specify which tools are allowed. - - `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"` - - `created_by: optional string` + - `"connector_microsoftteams"` - The ID of the entity that created this tool call. + - `"connector_outlookcalendar"` - - `ShellCallOutput object { id, call_id, max_output_length, 6 more }` + - `"connector_outlookemail"` - The output of a shell tool call that was emitted. + - `"connector_sharepoint"` - - `id: string` + - `defer_loading: optional boolean` - The unique ID of the shell call output. Populated when this item is returned via API. + Whether this MCP tool is deferred and discovered via tool search. - - `call_id: string` + - `headers: optional map[string]` - The unique ID of the shell tool call generated by the model. + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `max_output_length: number` + - `require_approval: optional object { always, never } or "always" or "never"` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + Specify which of the MCP server's tools require approval. - - `output: array of object { outcome, stderr, stdout, created_by }` + - `McpToolApprovalFilter object { always, never }` - An array of shell call output contents + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `outcome: object { type } or object { exit_code, type }` + - `always: optional 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"` + - `never: optional object { read_only, tool_names }` - - `Exit object { exit_code, type }` + A filter object to specify which tools are allowed. - Indicates that the shell commands finished and returned an exit code. + - `read_only: optional boolean` - - `exit_code: 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. - Exit code from the shell process. + - `tool_names: optional array of string` - - `type: "exit"` + List of allowed tool names. - The outcome type. Always `exit`. + - `McpToolApprovalSetting = "always" or "never"` - - `"exit"` + 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. - - `stderr: string` + - `"always"` - The standard error output that was captured. + - `"never"` - - `stdout: string` + - `server_description: optional string` - The standard output that was captured. + Optional description of the MCP server, used to provide more context. - - `created_by: optional string` + - `server_url: optional string` - The identifier of the actor that created the item. + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `status: "in_progress" or "completed" or "incomplete"` + - `tunnel_id: optional string` - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + 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. - - `"in_progress"` + - `CodeInterpreter object { container, type, allowed_callers }` - - `"completed"` + A tool that runs Python code to help generate a response to a prompt. - - `"incomplete"` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `type: "shell_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 shell call output. Always `shell_call_output`. + - `string` - - `"shell_call_output"` + 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`. - - `caller: optional object { type } or object { caller_id, type }` + - `"auto"` - The execution context that produced this tool call. + - `file_ids: optional array of string` - - `Direct object { type }` + An optional list of uploaded files to make available to your code. - - `type: "direct"` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `"direct"` + The memory limit for the code interpreter container. - - `Program object { caller_id, type }` + - `"1g"` - - `caller_id: string` + - `"4g"` - The call ID of the program item that produced this tool call. + - `"16g"` - - `type: "program"` + - `"64g"` - - `"program"` + - `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 }` - - `ApplyPatchCall object { id, call_id, operation, 5 more }` + - `type: "disabled"` - A tool call that applies file diffs by creating, deleting, or updating files. + Disable outbound network access. Always `disabled`. - - `id: string` + - `"disabled"` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `call_id: string` + - `allowed_domains: array of string` - The unique ID of the apply patch tool call generated by the model. + A list of allowed domains when type is `allowlist`. - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + - `type: "allowlist"` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + Allow outbound network access only to specified domains. Always `allowlist`. - - `CreateFile object { diff, path, type }` + - `"allowlist"` - Instruction describing how to create a file via the apply_patch tool. + - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` - - `diff: string` + Optional domain-scoped secrets for allowlisted domains. - Diff to apply. + - `domain: string` - - `path: string` + The domain associated with the secret. - Path of the file to create. + - `name: string` - - `type: "create_file"` + The name of the secret to inject for the domain. - Create a new file with the provided diff. + - `value: string` - - `"create_file"` + The secret value to inject for the domain. - - `DeleteFile object { path, type }` + - `type: "code_interpreter"` - Instruction describing how to delete a file via the apply_patch tool. + The type of the code interpreter tool. Always `code_interpreter`. - - `path: string` + - `"code_interpreter"` - Path of the file to delete. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `type: "delete_file"` + The tool invocation context(s). - Delete the specified file. + - `"direct"` - - `"delete_file"` + - `"programmatic"` - - `UpdateFile object { diff, path, type }` + - `ProgrammaticToolCalling object { type }` - Instruction describing how to update a file via the apply_patch tool. + - `type: "programmatic_tool_calling"` - - `diff: string` + The type of the tool. Always `programmatic_tool_calling`. - Diff to apply. + - `"programmatic_tool_calling"` - - `path: string` + - `ImageGeneration object { type, action, background, 9 more }` - Path of the file to update. + A tool that generates images using the GPT image models. - - `type: "update_file"` + - `type: "image_generation"` - Update an existing file with the provided diff. + The type of the image generation tool. Always `image_generation`. - - `"update_file"` + - `"image_generation"` - - `status: "in_progress" or "completed"` + - `action: optional "generate" or "edit" or "auto"` - The status of the apply patch tool call. One of `in_progress` or `completed`. + Whether to generate a new image or edit an existing image. Default: `auto`. - - `"in_progress"` + - `"generate"` - - `"completed"` + - `"edit"` - - `type: "apply_patch_call"` + - `"auto"` - The type of the item. Always `apply_patch_call`. + - `background: optional "transparent" or "opaque" or "auto"` - - `"apply_patch_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"` - - `created_by: optional string` + The image generation model to use. Default: `gpt-image-1`. - The ID of the entity that created this tool call. + - `string` - - `ApplyPatchCallOutput object { id, call_id, status, 5 more }` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - The output emitted by an apply patch tool call. + The image generation model to use. Default: `gpt-image-1`. - - `id: string` + - `"gpt-image-1"` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `"gpt-image-1-mini"` - - `call_id: string` + - `"gpt-image-1.5"` - The unique ID of the apply patch tool call generated by the model. + - `moderation: optional "auto" or "low"` - - `status: "completed" or "failed"` + Moderation level for the generated image. Default: `auto`. - The status of the apply patch tool call output. One of `completed` or `failed`. + - `"auto"` - - `"completed"` + - `"low"` - - `"failed"` + - `output_compression: optional number` - - `type: "apply_patch_call_output"` + Compression level for the output image. Default: 100. - The type of the item. Always `apply_patch_call_output`. + - `output_format: optional "png" or "webp" or "jpeg"` - - `"apply_patch_call_output"` + 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` - - `caller: optional object { type } or object { caller_id, type }` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - The execution context that produced this tool call. + - `quality: optional "low" or "medium" or "high" or "auto"` - - `Direct object { type }` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `type: "direct"` + - `"low"` - - `"direct"` + - `"medium"` - - `Program object { caller_id, type }` + - `"high"` - - `caller_id: string` + - `"auto"` - The call ID of the program item that produced this tool call. + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `type: "program"` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `"program"` + - `string` - - `created_by: optional string` + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - The ID of the entity that created this tool call output. + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `output: optional string` + - `"1024x1024"` - Optional textual output returned by the apply patch tool. + - `"1024x1536"` - - `McpCall object { id, arguments, name, 7 more }` + - `"1536x1024"` - An invocation of a tool on an MCP server. + - `"auto"` - - `id: string` + - `LocalShell object { type }` - The unique ID of the tool call. + A tool that allows the model to execute shell commands in a local environment. - - `arguments: string` + - `type: "local_shell"` - A JSON string of the arguments passed to the tool. + The type of the local shell tool. Always `local_shell`. - - `name: string` + - `"local_shell"` - The name of the tool that was run. + - `Shell object { type, allowed_callers, environment }` - - `server_label: string` + A tool that allows the model to execute shell commands. - The label of the MCP server running the tool. + - `type: "shell"` - - `type: "mcp_call"` + The type of the shell tool. Always `shell`. - The type of the item. Always `mcp_call`. + - `"shell"` - - `"mcp_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. + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - `approval_request_id: optional string` + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + - `type: "container_auto"` - - `error: optional string` + Automatically creates a container for this request - The error from the tool call, if any. + - `"container_auto"` - - `output: optional string` + - `file_ids: optional array of string` - The output from the tool call. + An optional list of uploaded files to make available to your code. - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + The memory limit for the container. - - `"in_progress"` + - `"1g"` - - `"completed"` + - `"4g"` - - `"incomplete"` + - `"16g"` - - `"calling"` + - `"64g"` - - `"failed"` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `McpListTools object { id, server_label, tools, 3 more }` + Network access policy for the container. - A list of tools available on an MCP server. + - `BetaContainerNetworkPolicyDisabled object { type }` - - `id: string` + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - The unique ID of the list. + - `skills: optional array of BetaSkillReference or BetaInlineSkill` - - `server_label: string` + An optional list of skills referenced by id or inline data. - The label of the MCP server. + - `BetaSkillReference object { skill_id, type, version }` - - `tools: array of object { input_schema, name, annotations, description }` + - `skill_id: string` - The tools available on the server. + The ID of the referenced skill. - - `input_schema: unknown` + - `type: "skill_reference"` - The JSON schema describing the tool's input. + References a skill created with the /v1/skills endpoint. - - `name: string` + - `"skill_reference"` - The name of the tool. + - `version: optional string` - - `annotations: optional unknown` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - Additional annotations about the tool. + - `BetaInlineSkill object { description, name, source, type }` - - `description: optional string` + - `description: string` - The description of the tool. + The description of the skill. - - `type: "mcp_list_tools"` + - `name: string` - The type of the item. Always `mcp_list_tools`. + The name of the skill. - - `"mcp_list_tools"` + - `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"` - - `error: optional string` + The media type of the inline skill payload. Must be `application/zip`. - Error message if the server could not list tools. + - `"application/zip"` - - `McpApprovalRequest object { id, arguments, name, 3 more }` + - `type: "base64"` - A request for human approval of a tool invocation. + The type of the inline skill source. Must be `base64`. - - `id: string` + - `"base64"` - The unique ID of the approval request. + - `type: "inline"` - - `arguments: string` + Defines an inline skill for this request. - A JSON string of arguments for the tool. + - `"inline"` - - `name: string` + - `BetaLocalEnvironment object { type, skills }` - The name of the tool to run. + - `type: "local"` - - `server_label: string` + Use a local computer environment. - The label of the MCP server making the request. + - `"local"` - - `type: "mcp_approval_request"` + - `skills: optional array of BetaLocalSkill` - The type of the item. Always `mcp_approval_request`. + An optional list of skills. - - `"mcp_approval_request"` + - `description: string` - - `agent: optional object { agent_name }` + The description of the skill. - The agent that produced this item. + - `name: string` - - `agent_name: string` + The name of the skill. - The canonical name of the agent that produced this item. + - `path: string` - - `McpApprovalResponse object { id, approval_request_id, approve, 3 more }` + The path to the directory containing the skill. - A response to an MCP approval request. + - `BetaContainerReference object { container_id, type }` - - `id: string` + - `container_id: string` - The unique ID of the approval response + The ID of the referenced container. - - `approval_request_id: string` + - `type: "container_reference"` - The ID of the approval request being answered. + References a container created with the /v1/containers endpoint - - `approve: boolean` + - `"container_reference"` - Whether the request was approved. + - `Custom object { name, type, allowed_callers, 3 more }` - - `type: "mcp_approval_response"` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - The type of the item. Always `mcp_approval_response`. + - `name: string` - - `"mcp_approval_response"` + 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"` - - `reason: optional string` + The tool invocation context(s). - Optional reason for the decision. + - `"direct"` - - `CustomToolCall object { call_id, input, name, 5 more }` + - `"programmatic"` - A call to a custom tool created by the model. + - `defer_loading: optional boolean` - - `call_id: string` + Whether this tool should be deferred and discovered via tool search. - An identifier used to map this custom tool call to a tool call output. + - `description: optional string` - - `input: string` + Optional description of the custom tool, used to provide more context. - The input for the custom tool call generated by the model. + - `format: optional object { type } or object { definition, syntax, type }` - - `name: string` + The input format for the custom tool. Default is unconstrained text. - The name of the custom tool being called. + - `Text object { type }` - - `type: "custom_tool_call"` + Unconstrained free-form text. - The type of the custom tool call. Always `custom_tool_call`. + - `type: "text"` - - `"custom_tool_call"` + Unconstrained text format. Always `text`. - - `id: optional string` + - `"text"` - The unique ID of the custom tool call in the OpenAI platform. + - `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"` - - `"direct"` + Grammar format. Always `grammar`. - - `Program object { caller_id, type }` + - `"grammar"` - - `caller_id: string` + - `Namespace object { description, name, tools, type }` - The call ID of the program item that produced this tool call. + Groups function/custom tools under a shared namespace. - - `type: "program"` + - `description: string` - - `"program"` + A description of the namespace shown to the model. - - `namespace: optional string` + - `name: string` - The namespace of the custom tool being called. + The namespace name used in tool calls (for example, `crm`). - - `CustomToolCallOutput object { id, call_id, output, 5 more }` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - - `id: string` + The function/custom tools available inside this namespace. - The unique ID of the custom tool call output item. + - `Function object { name, type, allowed_callers, 5 more }` - - `call_id: string` + - `name: string` - The call ID, used to map this custom tool call output to a custom tool call. + - `type: "function"` - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `"function"` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `StringOutput = string` + The tool invocation context(s). - A string of the output of the custom tool call. + - `"direct"` - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `"programmatic"` - Text, image, or file output of the custom tool call. + - `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` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `output_schema: optional map[unknown]` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `parameters: optional unknown` - A file input to the model. + - `strict: optional boolean` - - `status: "in_progress" or "completed" or "incomplete"` + 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 status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `Custom object { name, type, allowed_callers, 3 more }` - - `"in_progress"` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `"completed"` + - `name: string` - - `"incomplete"` + The name of the custom tool, used to identify it in tool calls. - - `type: "custom_tool_call_output"` + - `type: "custom"` - The type of the custom tool call output. Always `custom_tool_call_output`. + The type of the custom tool. Always `custom`. - - `"custom_tool_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"` - - `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 }` - - `created_by: optional string` + A grammar defined by the user. - The identifier of the actor that created the item. + - `definition: string` - - `parallel_tool_calls: boolean` + The grammar definition. - Whether to allow the model to run tool calls in parallel. + - `syntax: "lark" or "regex"` - - `temperature: number` + The syntax of the grammar definition. One of `lark` or `regex`. - 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. + - `"lark"` - - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` + - `"regex"` - 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: "grammar"` - - `BetaToolChoiceOptions = "none" or "auto" or "required"` + Grammar format. Always `grammar`. - Controls which (if any) tool is called by the model. + - `"grammar"` - `none` means the model will not call any tool and instead generates a message. + - `type: "namespace"` - `auto` means the model can pick between generating a message or calling one or - more tools. + The type of the tool. Always `namespace`. - `required` means the model must call one or more tools. + - `"namespace"` - - `"none"` + - `ToolSearch object { type, description, execution, parameters }` - - `"auto"` + Hosted or BYOT tool search configuration for deferred tools. - - `"required"` + - `type: "tool_search"` - - `BetaToolChoiceAllowed object { mode, tools, type }` + The type of the tool. Always `tool_search`. - Constrains the tools available to the model to a pre-defined set. + - `"tool_search"` - - `mode: "auto" or "required"` + - `description: optional string` - Constrains the tools available to the model to a pre-defined set. + Description shown to the model for a client-executed tool search tool. - `auto` allows the model to pick from among the allowed tools and generate a - message. + - `execution: optional "server" or "client"` - `required` requires the model to call one or more of the allowed tools. + Whether tool search is executed by the server or by the client. - - `"auto"` + - `"server"` - - `"required"` + - `"client"` - - `tools: array of map[unknown]` + - `parameters: optional unknown` - A list of tool definitions that the model should be allowed to call. + Parameter schema for a client-executed tool search tool. - For the Responses API, the list of tool definitions might look like: + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + 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: "allowed_tools"` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - Allowed tool configuration type. Always `allowed_tools`. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `"allowed_tools"` + - `"web_search_preview"` - - `BetaToolChoiceTypes object { type }` + - `"web_search_preview_2025_03_11"` - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + - `search_content_types: optional array of "text" or "image"` - - `type: "file_search" or "web_search_preview" or "computer" or 5 more` + - `"text"` - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + - `"image"` - Allowed values are: + - `search_context_size: optional "low" or "medium" or "high"` - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + 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"` + - `"low"` - - `"web_search_preview"` + - `"medium"` - - `"computer"` + - `"high"` - - `"computer_use_preview"` + - `user_location: optional object { type, city, country, 2 more }` - - `"computer_use"` + The user's location. - - `"web_search_preview_2025_03_11"` + - `type: "approximate"` - - `"image_generation"` + The type of location approximation. Always `approximate`. - - `"code_interpreter"` + - `"approximate"` - - `BetaToolChoiceFunction object { name, type }` + - `city: optional string` - Use this option to force the model to call a specific function. + Free text input for the city of the user, e.g. `San Francisco`. - - `name: string` + - `country: optional string` - The name of the function to call. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `type: "function"` + - `region: optional string` - For function calling, the type is always `function`. + Free text input for the region of the user, e.g. `California`. - - `"function"` + - `timezone: optional string` - - `BetaToolChoiceMcp object { server_label, type, name }` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - Use this option to force the model to call a specific tool on a remote MCP server. + - `ApplyPatch object { type, allowed_callers }` - - `server_label: string` + Allows the assistant to create, delete, or update files using unified diffs. - The label of the MCP server to use. + - `type: "apply_patch"` - - `type: "mcp"` + The type of the tool. Always `apply_patch`. - For MCP tools, the type is always `mcp`. + - `"apply_patch"` - - `"mcp"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `name: optional string` + The tool invocation context(s). - The name of the tool to call on the server. + - `"direct"` - - `BetaToolChoiceCustom object { name, type }` + - `"programmatic"` - Use this option to force the model to call a specific custom tool. + - `type: "tool_search_output"` - - `name: string` + The type of the item. Always `tool_search_output`. - The name of the custom tool to call. + - `"tool_search_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` - - `BetaSpecificProgrammaticToolCallingParam object { type }` + The canonical name of the agent that produced this item. - - `type: "programmatic_tool_calling"` + - `created_by: optional string` - The tool to call. Always `programmatic_tool_calling`. + The identifier of the actor that created the item. - - `"programmatic_tool_calling"` + - `AdditionalTools object { id, role, tools, 2 more }` - - `BetaToolChoiceApplyPatch object { type }` + - `id: string` - Forces the model to call the apply_patch tool when executing a tool call. + The unique ID of the additional tools item. - - `type: "apply_patch"` + - `role: "unknown" or "user" or "assistant" or 5 more` - The tool to call. Always `apply_patch`. + The role that provided the additional tools. - - `"apply_patch"` + - `"unknown"` - - `BetaToolChoiceShell object { type }` + - `"user"` - Forces the model to call the shell tool when a tool call is required. + - `"assistant"` - - `type: "shell"` + - `"system"` - The tool to call. Always `shell`. + - `"critic"` - - `"shell"` + - `"discriminator"` - - `tools: 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. + - `"tool"` - 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](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/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](https://platform.openai.com/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](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. + The additional tool definitions made available at this item. - `Function object { name, parameters, strict, 5 more }` @@ -142946,7 +140324,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-web-search). + [web search tool](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -143006,7 +140384,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -143058,7 +140436,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -143250,19 +140628,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `background: optional "transparent" or "opaque" or "auto"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. - - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. - - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - `"transparent"` @@ -143291,13 +140658,13 @@ curl -X POST https://api.openai.com/v1/responses/compact \ Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `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-2" or 3 more` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` The image generation model to use. Default: `gpt-image-1`. @@ -143305,14 +140672,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"gpt-image-1-mini"` - - `"gpt-image-2"` - - - `"gpt-image-2-2026-04-21"` - - `"gpt-image-1.5"` - - `"chatgpt-image-latest"` - - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -143409,7 +140770,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -143523,7 +140884,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -143691,758 +141052,1005 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"programmatic"` - - `top_p: number` + - `type: "additional_tools"` - An alternative to sampling with temperature, called nucleus sampling, - where the model considers the results of the tokens with top_p probability - mass. So 0.1 means only the tokens comprising the top 10% probability mass - are considered. + The type of the item. Always `additional_tools`. - We generally recommend altering this or `temperature` but not both. + - `"additional_tools"` - - `background: optional boolean` + - `agent: optional object { agent_name }` - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + The agent that produced this item. - - `completed_at: optional number` + - `agent_name: string` - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + The canonical name of the agent that produced this item. - - `conversation: optional object { id }` + - `Compaction object { id, encrypted_content, type, 2 more }` - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). - `id: string` - The unique ID of the conversation that this response was associated with. + The unique ID of the compaction item. - - `max_output_tokens: optional number` + - `encrypted_content: string` - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + The encrypted content that was produced by compaction. - - `max_tool_calls: optional number` + - `type: "compaction"` - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + The type of the item. Always `compaction`. - - `moderation: optional object { input, output }` + - `"compaction"` - Moderation results for the response input and output, if moderated completions were requested. + - `agent: optional object { agent_name }` - - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + The agent that produced this item. - Moderation for the response input. + - `agent_name: string` - - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` + The canonical name of the agent that produced this item. - A moderation result produced for the response input or output. + - `created_by: optional string` - - `categories: map[boolean]` + The identifier of the actor that created the item. - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `ImageGenerationCall object { id, result, status, 2 more }` - - `category_applied_input_types: map[array of "text" or "image"]` + An image generation request made by the model. - Which modalities of input are reflected by the score for each category. + - `id: string` - - `"text"` + The unique ID of the image generation call. - - `"image"` + - `result: string` - - `category_scores: map[number]` + The generated image encoded in base64. - A dictionary of moderation categories to scores. + - `status: "in_progress" or "completed" or "generating" or "failed"` - - `flagged: boolean` + The status of the image generation call. - A boolean indicating whether the content was flagged by any category. + - `"in_progress"` - - `model: string` + - `"completed"` - The moderation model that produced this result. + - `"generating"` - - `type: "moderation_result"` + - `"failed"` - The object type, which was always `moderation_result` for successful moderation results. + - `type: "image_generation_call"` - - `"moderation_result"` + The type of the image generation call. Always `image_generation_call`. - - `Error object { code, message, type }` + - `"image_generation_call"` - An error produced while attempting moderation for the response input or 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. + + - `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 error code. + The code to run, or null if not available. - - `message: string` + - `container_id: string` - The error message. + The ID of the container used to run the code. - - `type: "error"` + - `outputs: array of object { logs, type } or object { type, url }` - The object type, which was always `error` for moderation failures. + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `"error"` + - `Logs object { logs, type }` - - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + The logs output from the code interpreter. - Moderation for the response output. + - `logs: string` - - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` + The logs output from the code interpreter. - A moderation result produced for the response input or output. + - `type: "logs"` - - `categories: map[boolean]` + The type of the output. Always `logs`. - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `"logs"` - - `category_applied_input_types: map[array of "text" or "image"]` + - `Image object { type, url }` - Which modalities of input are reflected by the score for each category. + The image output from the code interpreter. - - `"text"` + - `type: "image"` + + The type of the output. Always `image`. - `"image"` - - `category_scores: map[number]` + - `url: string` - A dictionary of moderation categories to scores. + The URL of the image output from the code interpreter. - - `flagged: boolean` + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - A boolean indicating whether the content was flagged by any category. + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `model: string` + - `"in_progress"` - The moderation model that produced this result. + - `"completed"` - - `type: "moderation_result"` + - `"incomplete"` - The object type, which was always `moderation_result` for successful moderation results. + - `"interpreting"` - - `"moderation_result"` + - `"failed"` - - `Error object { code, message, type }` + - `type: "code_interpreter_call"` - An error produced while attempting moderation for the response input or output. + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `code: string` + - `"code_interpreter_call"` - The error code. + - `agent: optional object { agent_name }` - - `message: string` + The agent that produced this item. - The error message. + - `agent_name: string` - - `type: "error"` + The canonical name of the agent that produced this item. - The object type, which was always `error` for moderation failures. + - `LocalShellCall object { id, action, call_id, 3 more }` - - `"error"` + A tool call to run a command on the local shell. - - `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](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + The unique ID of the local shell call. - - `prompt: optional BetaResponsePrompt` + - `action: object { command, env, type, 3 more }` - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + 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 identifier of the prompt template to use. + The unique ID of the local shell tool call generated by the model. - - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` + - `output: 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. + A JSON string of the output of the local shell tool call. - - `string` + - `type: "local_shell_call_output"` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + The type of the local shell tool call output. Always `local_shell_call_output`. - A text input to the model. + - `"local_shell_call_output"` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `agent: optional object { agent_name }` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + 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. - - `version: optional string` + - `status: optional "in_progress" or "completed" or "incomplete"` - Optional version of the prompt template. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `prompt_cache_key: optional string` + - `"in_progress"` - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + - `"completed"` - - `prompt_cache_options: optional object { mode, ttl }` + - `"incomplete"` - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + - `ShellCall object { id, action, call_id, 6 more }` - - `mode: "implicit" or "explicit"` + A tool call that executes one or more shell commands in a managed environment. - Whether implicit prompt-cache breakpoints were enabled. + - `id: string` - - `"implicit"` + The unique ID of the shell tool call. Populated when this item is returned via API. - - `"explicit"` + - `action: object { commands, max_output_length, timeout_ms }` - - `ttl: "30m"` + The shell commands and limits that describe how to run the tool call. - The minimum lifetime applied to each cache breakpoint. + - `commands: array of string` - - `"30m"` + - `max_output_length: number` - - `prompt_cache_retention: optional "in_memory" or "24h"` + Optional maximum number of characters to return from each command. - Deprecated. Use `prompt_cache_options.ttl` instead. + - `timeout_ms: 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](https://platform.openai.com/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. + 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` + + 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 + + - `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. + + - `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` + + Exit code from the shell process. + + - `type: "exit"` + + The outcome type. Always `exit`. + + - `"exit"` + + - `stderr: string` + + The standard error output that was captured. + + - `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"` + + - `type: "shell_call_output"` + + The type of the shell call output. Always `shell_call_output`. + + - `"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"` + + - `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 }` - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + Instruction describing how to update a file via the apply_patch tool. - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `diff: string` - - `"in_memory"` + Diff to apply. - - `"24h"` + - `path: string` - - `reasoning: optional object { context, effort, generate_summary, 2 more }` + Path of the file to update. - **gpt-5 and o-series models only** + - `type: "update_file"` - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + Update an existing file with the provided diff. - - `context: optional "auto" or "current_turn" or "all_turns"` + - `"update_file"` - Controls which reasoning items are rendered back to the model on later turns. - When returned on a response, this is the effective reasoning context mode - used for the response. + - `status: "in_progress" or "completed"` - - `"auto"` + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `"current_turn"` + - `"in_progress"` - - `"all_turns"` + - `"completed"` - - `effort: optional "none" or "minimal" or "low" or 4 more` + - `type: "apply_patch_call"` - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + The type of the item. Always `apply_patch_call`. - - `"none"` + - `"apply_patch_call"` - - `"minimal"` + - `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. - - `"xhigh"` + - `caller: optional object { type } or object { caller_id, type }` - - `"max"` + The execution context that produced this tool call. - - `generate_summary: optional "auto" or "concise" or "detailed"` + - `Direct object { type }` - **Deprecated:** use `summary` instead. + - `type: "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`. + - `"direct"` - - `"auto"` + - `Program object { caller_id, type }` - - `"concise"` + - `caller_id: string` - - `"detailed"` + The call ID of the program item that produced this tool call. - - `mode: optional string or "standard" or "pro"` + - `type: "program"` - Controls the reasoning execution mode for the request. + - `"program"` - When returned on a response, this is the effective execution mode. + - `created_by: optional string` - - `string` + The ID of the entity that created this tool call. - - `"standard" or "pro"` + - `ApplyPatchCallOutput object { id, call_id, status, 5 more }` - Controls the reasoning execution mode for the request. + The output emitted by an apply patch tool call. - When returned on a response, this is the effective execution mode. + - `id: string` - - `"standard"` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `"pro"` + - `call_id: string` - - `summary: optional "auto" or "concise" or "detailed"` + The unique ID of the apply patch tool call generated by 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`. + - `status: "completed" or "failed"` - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + The status of the apply patch tool call output. One of `completed` or `failed`. - - `"auto"` + - `"completed"` - - `"concise"` + - `"failed"` - - `"detailed"` + - `type: "apply_patch_call_output"` - - `safety_identifier: optional string` + The type of the item. Always `apply_patch_call_output`. - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `"apply_patch_call_output"` - - `service_tier: optional "auto" or "default" or "flex" or 2 more` + - `agent: optional object { agent_name }` - Specifies the processing type used for serving the request. + The agent that produced this item. - - 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](https://platform.openai.com/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'. + - `agent_name: 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 canonical name of the agent that produced this item. - - `"auto"` + - `caller: optional object { type } or object { caller_id, type }` - - `"default"` + The execution context that produced this tool call. - - `"flex"` + - `Direct object { type }` - - `"scale"` + - `type: "direct"` - - `"priority"` + - `"direct"` - - `status: optional BetaResponseStatus` + - `Program object { caller_id, type }` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + - `caller_id: string` - - `"completed"` + The call ID of the program item that produced this tool call. - - `"failed"` + - `type: "program"` - - `"in_progress"` + - `"program"` - - `"cancelled"` + - `created_by: optional string` - - `"queued"` + The ID of the entity that created this tool call output. - - `"incomplete"` + - `output: optional string` - - `text: optional BetaResponseTextConfig` + Optional textual output returned by the apply patch tool. - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + - `McpCall object { id, arguments, name, 7 more }` - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + An invocation of a tool on an MCP server. - - `format: optional BetaResponseFormatTextConfig` + - `id: string` - An object specifying the format that the model must output. + The unique ID of the tool call. - Configuring `{ "type": "json_schema" }` enables Structured Outputs, - which ensures the model will match your supplied JSON schema. Learn more in the - [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `arguments: string` - The default format is `{ "type": "text" }` with no additional options. + A JSON string of the arguments passed to the tool. - **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 tool that was run. - - `Text object { type }` + - `server_label: string` - Default response format. Used to generate text responses. + The label of the MCP server running the tool. - - `type: "text"` + - `type: "mcp_call"` - The type of response format being defined. Always `text`. + The type of the item. Always `mcp_call`. - - `"text"` + - `"mcp_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](https://platform.openai.com/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]` + - `approval_request_id: 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/). + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - - `type: "json_schema"` + - `error: optional string` - The type of response format being defined. Always `json_schema`. + The error from the tool call, if any. - - `"json_schema"` + - `output: optional string` - - `description: optional string` + The output from the tool call. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - - `strict: optional boolean` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - 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](https://platform.openai.com/docs/guides/structured-outputs). + - `"in_progress"` - - `JSONObject object { type }` + - `"completed"` - 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. + - `"incomplete"` - - `type: "json_object"` + - `"calling"` - The type of response format being defined. Always `json_object`. + - `"failed"` - - `"json_object"` + - `McpListTools object { id, server_label, tools, 3 more }` - - `verbosity: optional "low" or "medium" or "high"` + A list of tools available on an MCP server. - 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`. + - `id: string` - - `"low"` + The unique ID of the list. - - `"medium"` + - `server_label: string` - - `"high"` + The label of the MCP server. - - `top_logprobs: optional number` + - `tools: array of object { input_schema, name, annotations, description }` - 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 tools available on the server. - - `truncation: optional "auto" or "disabled"` + - `input_schema: unknown` - The truncation strategy to use for the model response. + The JSON schema describing the tool's input. - - `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. + - `name: string` - - `"auto"` + The name of the tool. - - `"disabled"` + - `annotations: optional unknown` - - `usage: optional BetaResponseUsage` + Additional annotations about the tool. - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + - `description: optional string` - - `input_tokens: number` + The description of the tool. - The number of input tokens. + - `type: "mcp_list_tools"` - - `input_tokens_details: object { cache_write_tokens, cached_tokens }` + The type of the item. Always `mcp_list_tools`. - A detailed breakdown of the input tokens. + - `"mcp_list_tools"` - - `cache_write_tokens: number` + - `agent: optional object { agent_name }` - The number of input tokens that were written to the cache. + The agent that produced this item. - - `cached_tokens: number` + - `agent_name: string` - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + The canonical name of the agent that produced this item. - - `output_tokens: number` + - `error: optional string` - The number of output tokens. + Error message if the server could not list tools. - - `output_tokens_details: object { reasoning_tokens }` + - `McpApprovalRequest object { id, arguments, name, 3 more }` - A detailed breakdown of the output tokens. + A request for human approval of a tool invocation. - - `reasoning_tokens: number` + - `id: string` - The number of reasoning tokens. + The unique ID of the approval request. - - `total_tokens: number` + - `arguments: string` - The total number of tokens used. + A JSON string of arguments for the tool. - - `user: optional string` + - `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](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + 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.incomplete"` + - `type: "mcp_approval_request"` - The type of the event. Always `response.incomplete`. + The type of the item. Always `mcp_approval_request`. - - `"response.incomplete"` + - `"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. -### Beta Response Input + - `McpApprovalResponse object { id, approval_request_id, approve, 3 more }` -- `BetaResponseInput = array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + A response to an MCP approval request. - A list of one or many input items to the model, containing - different content types. + - `id: string` - - `BetaEasyInputMessage object { content, role, phase, type }` + The unique ID of the approval response - 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. + - `approval_request_id: string` - - `content: string or BetaResponseInputMessageContentList` + The ID of the approval request being answered. - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + - `approve: boolean` - - `TextInput = string` + Whether the request was approved. - A text input to the model. + - `type: "mcp_approval_response"` - - `BetaResponseInputMessageContentList = array of BetaResponseInputContent` + The type of the item. Always `mcp_approval_response`. - A list of one or many input items to the model, containing different content - types. + - `"mcp_approval_response"` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `agent: optional object { agent_name }` - A text input to the model. + The agent that produced this item. - - `text: string` + - `agent_name: string` - The text input to the model. + The canonical name of the agent that produced this item. - - `type: "input_text"` + - `reason: optional string` - The type of the input item. Always `input_text`. + Optional reason for the decision. - - `"input_text"` + - `CustomToolCall object { call_id, input, name, 5 more }` - - `prompt_cache_breakpoint: optional object { mode }` + A call to a custom tool created 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. + - `call_id: string` - - `mode: "explicit"` + An identifier used to map this custom tool call to a tool call output. - The breakpoint mode. Always `explicit`. + - `input: string` - - `"explicit"` + The input for the custom tool call generated by the model. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `name: string` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The name of the custom tool being called. - - `detail: "low" or "high" or "auto" or "original"` + - `type: "custom_tool_call"` - 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 custom tool call. Always `custom_tool_call`. - - `"low"` + - `"custom_tool_call"` - - `"high"` + - `id: optional string` - - `"auto"` + The unique ID of the custom tool call in the OpenAI platform. - - `"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` + - `caller: optional object { type } or object { caller_id, type }` - The ID of the file to be sent to the model. + The execution context that produced this tool call. - - `image_url: optional string` + - `Direct 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. + - `type: "direct"` - - `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. + - `Program object { caller_id, type }` - - `mode: "explicit"` + - `caller_id: string` - The breakpoint mode. Always `explicit`. + The call ID of the program item that produced this tool call. - - `"explicit"` + - `type: "program"` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `"program"` - A file input to the model. + - `namespace: optional string` - - `type: "input_file"` + The namespace of the custom tool being called. - The type of the input item. Always `input_file`. + - `CustomToolCallOutput object { id, call_id, output, 5 more }` - - `"input_file"` + - `id: string` - - `detail: optional "auto" or "low" or "high"` + The unique ID of the custom tool call output 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`. + - `call_id: string` - - `"auto"` + 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` - - `"high"` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `file_data: optional string` + - `StringOutput = string` - The content of the file to be sent to the model. + A string of the output of the custom tool call. - - `file_id: optional string` + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - The ID of the file to be sent to the model. + Text, image, or file output of the custom tool call. - - `file_url: optional string` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - The URL of the file to be sent to the model. + A text input to the model. - - `filename: optional string` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - The name of the file to be sent to the model. + 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"` - - `role: "user" or "assistant" or "system" or "developer"` + - `"completed"` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + - `"incomplete"` - - `"user"` + - `type: "custom_tool_call_output"` - - `"assistant"` + The type of the custom tool call output. Always `custom_tool_call_output`. - - `"system"` + - `"custom_tool_call_output"` - - `"developer"` + - `agent: optional object { agent_name }` - - `phase: optional "commentary" or "final_answer"` + The agent that produced this 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. + - `agent_name: string` - - `"commentary"` + The canonical name of the agent that produced this item. - - `"final_answer"` + - `caller: optional object { type } or object { caller_id, type }` - - `type: optional "message"` + The execution context that produced this tool call. - The type of the message input. Always `message`. + - `Direct object { type }` - - `"message"` + - `type: "direct"` - - `Message object { content, role, agent, 2 more }` + The caller type. Always `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. + - `"direct"` - - `content: BetaResponseInputMessageContentList` + - `Program object { caller_id, type }` - A list of one or many input items to the model, containing different content - types. + - `caller_id: string` - - `role: "user" or "system" or "developer"` + The call ID of the program item that produced this tool call. - The role of the message input. One of `user`, `system`, or `developer`. + - `type: "program"` - - `"user"` + The caller type. Always `program`. - - `"system"` + - `"program"` - - `"developer"` + - `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` - - `status: optional "in_progress" or "completed" or "incomplete"` + The sequence number of this event. - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `type: "response.output_item.added"` - - `"in_progress"` + The type of the event. Always `response.output_item.added`. - - `"completed"` + - `"response.output_item.added"` - - `"incomplete"` + - `agent: optional object { agent_name }` - - `type: optional "message"` + The agent that owns this multi-agent streaming event. - The type of the message input. Always set to `message`. + - `agent_name: string` - - `"message"` + The canonical name of the agent that produced this item. + +### Beta Response Output Item Done Event + +- `BetaResponseOutputItemDoneEvent object { item, output_index, sequence_number, 2 more }` + + Emitted when an output item is marked done. + + - `item: BetaResponseOutputItem` + + The output item that was marked done. - `BetaResponseOutputMessage object { id, content, role, 4 more }` @@ -144456,7 +142064,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The content of the output message. - - `BetaResponseOutputText object { annotations, text, type, logprobs }` + - `BetaResponseOutputText object { annotations, logprobs, text, type }` A text output from the model. @@ -144560,17 +142168,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"file_path"` - - `text: string` - - The text output from the model. - - - `type: "output_text"` - - The type of the output text. Always `output_text`. - - - `"output_text"` - - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - `token: string` @@ -144586,6 +142184,16 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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. @@ -144644,7 +142252,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `FileSearchCall object { id, queries, status, 3 more }` The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + [file search guide](/docs/guides/tools-file-search) for more information. - `id: string` @@ -144717,36 +142325,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](https://platform.openai.com/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. @@ -144757,308 +142395,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 }` @@ -145068,20 +142769,68 @@ 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 }` The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + [web search guide](/docs/guides/tools-web-search) for more information. - `id: string` @@ -145182,349 +142931,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](https://platform.openai.com/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 BetaResponseFunctionCallOutputItemList` + - `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. - - `BetaResponseFunctionCallOutputItemList = array of BetaResponseFunctionCallOutputItem` + - `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](https://platform.openai.com/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](https://platform.openai.com/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 }` @@ -145534,127 +143294,138 @@ 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 array of object { end_index, start_index, title, 2 more } or array of 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. - - `array of 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 - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - - `"file_citation"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `array of 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` - - `array of 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 }` @@ -145664,21 +143435,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 }` @@ -145688,11 +143481,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. @@ -145700,9 +143503,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"` @@ -145710,11 +143513,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 }` @@ -145977,7 +143778,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-web-search). + [web search tool](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -146037,7 +143838,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -146089,7 +143890,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -146313,19 +144114,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `background: optional "transparent" or "opaque" or "auto"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. - - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. - - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - `"transparent"` @@ -146354,13 +144144,13 @@ curl -X POST https://api.openai.com/v1/responses/compact \ Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `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-2" or 3 more` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` The image generation model to use. Default: `gpt-image-1`. @@ -146368,14 +144158,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"gpt-image-1-mini"` - - `"gpt-image-2"` - - - `"gpt-image-2-2026-04-21"` - - `"gpt-image-1.5"` - - `"chatgpt-image-latest"` - - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -146590,7 +144374,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -146704,7 +144488,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -146874,14 +144658,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. @@ -146890,39 +144670,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 }` @@ -147185,7 +144965,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-web-search). + [web search tool](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -147245,7 +145025,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -147297,7 +145077,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -147489,19 +145269,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `background: optional "transparent" or "opaque" or "auto"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. - - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. - - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - `"transparent"` @@ -147530,13 +145299,13 @@ curl -X POST https://api.openai.com/v1/responses/compact \ Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `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-2" or 3 more` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` The image generation model to use. Default: `gpt-image-1`. @@ -147544,14 +145313,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"gpt-image-1-mini"` - - `"gpt-image-2"` - - - `"gpt-image-2-2026-04-21"` - - `"gpt-image-1.5"` - - `"chatgpt-image-latest"` - - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -147648,7 +145411,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -147762,7 +145525,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -147932,13 +145695,745 @@ 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` + - `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` + + 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 + + - `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. + + - `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` + + Exit code from the shell process. + + - `type: "exit"` + + The outcome type. Always `exit`. + + - `"exit"` + + - `stderr: string` + + The standard error output that was captured. + + - `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"` + + - `type: "shell_call_output"` + + The type of the shell call output. Always `shell_call_output`. + + - `"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"` + + - `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`. - The unique ID of this additional tools item. + - `"mcp_list_tools"` - `agent: optional object { agent_name }` @@ -147948,36 +146443,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](https://platform.openai.com/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 }` @@ -147987,53 +146481,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 - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. - - - `status: optional "in_progress" or "completed" or "incomplete"` - - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - - - `"in_progress"` - - - `"completed"` + - `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](https://platform.openai.com/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 }` @@ -148043,35 +146511,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 }` @@ -148081,58 +146549,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"` @@ -148140,15 +146619,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 }` @@ -148158,249 +146633,236 @@ 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]` + - `caller: optional object { type } or object { caller_id, type }` - Environment variables to set for the command. + The execution context that produced this tool call. - - `type: "exec"` + - `Direct object { type }` - The type of the local shell action. Always `exec`. + - `type: "direct"` - - `"exec"` + The caller type. Always `direct`. - - `timeout_ms: optional number` + - `"direct"` - Optional timeout in milliseconds for the command. + - `Program object { caller_id, type }` - - `user: optional string` + - `caller_id: string` - Optional user to run the command as. + The call ID of the program item that produced this tool call. - - `working_directory: optional string` + - `type: "program"` - Optional working directory to run the command in. + The caller type. Always `program`. - - `call_id: string` + - `"program"` - The unique ID of the local shell tool call generated by the model. + - `created_by: optional string` - - `status: "in_progress" or "completed" or "incomplete"` + The identifier of the actor that created the item. - The status of the local shell call. + - `output_index: number` - - `"in_progress"` + The index of the output item that was marked done. - - `"completed"` + - `sequence_number: number` - - `"incomplete"` + The sequence number of this event. - - `type: "local_shell_call"` + - `type: "response.output_item.done"` - The type of the local shell call. Always `local_shell_call`. + The type of the event. Always `response.output_item.done`. - - `"local_shell_call"` + - `"response.output_item.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. - - `LocalShellCallOutput object { id, output, type, 2 more }` +### Beta Response Output Message - The output of a local shell tool call. +- `BetaResponseOutputMessage object { id, content, role, 4 more }` + + An output message from the model. - `id: string` - The unique ID of the local shell tool call generated by the model. + The unique ID of the output message. - - `output: string` + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - A JSON string of the output of the local shell tool call. + The content of the output message. - - `type: "local_shell_call_output"` + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - The type of the local shell tool call output. Always `local_shell_call_output`. + A text output from the model. - - `"local_shell_call_output"` + - `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` - - `status: optional "in_progress" or "completed" or "incomplete"` + The ID of the file. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `filename: string` - - `"in_progress"` + The filename of the file cited. - - `"completed"` + - `index: number` - - `"incomplete"` + The index of the file in the list of files. - - `ShellCall object { action, call_id, type, 5 more }` + - `type: "file_citation"` - A tool representing a request to execute one or more shell commands. + The type of the file citation. Always `file_citation`. - - `action: object { commands, max_output_length, timeout_ms }` + - `"file_citation"` - The shell commands and limits that describe how to run the tool call. + - `URLCitation object { end_index, start_index, title, 2 more }` - - `commands: array of string` + A citation for a web resource used to generate a model response. - Ordered shell commands for the execution environment to run. + - `end_index: number` - - `max_output_length: optional number` + The index of the last character of the URL citation in the message. - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + - `start_index: number` - - `timeout_ms: optional number` + The index of the first character of the URL citation in the message. - Maximum wall-clock time in milliseconds to allow the shell commands to run. + - `title: string` - - `call_id: string` + The title of the web resource. - The unique ID of the shell tool call generated by the model. + - `type: "url_citation"` - - `type: "shell_call"` + The type of the URL citation. Always `url_citation`. - The type of the item. Always `shell_call`. + - `"url_citation"` - - `"shell_call"` + - `url: string` - - `id: optional string` + The URL of the web resource. - The unique ID of the shell tool call. Populated when this item is returned via API. + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - - `agent: optional object { agent_name }` + A citation for a container file used to generate a model response. - The agent that produced this item. + - `container_id: string` - - `agent_name: string` + The ID of the container file. - The canonical name of the agent that produced this item. + - `end_index: number` - - `caller: optional object { type } or object { caller_id, type }` + The index of the last character of the container file citation in the message. - The execution context that produced this tool call. + - `file_id: string` - - `Direct object { type }` + The ID of the file. - - `type: "direct"` + - `filename: string` - The caller type. Always `direct`. + The filename of the container file cited. - - `"direct"` + - `start_index: number` - - `Program object { caller_id, type }` + The index of the first character of the container file citation in the message. - - `caller_id: string` + - `type: "container_file_citation"` - The call ID of the program item that produced this tool call. + The type of the container file citation. Always `container_file_citation`. - - `type: "program"` + - `"container_file_citation"` - The caller type. Always `program`. + - `FilePath object { file_id, index, type }` - - `"program"` + A path to a file. - - `environment: optional BetaLocalEnvironment or BetaContainerReference` + - `file_id: string` - The environment to execute the shell commands in. + The ID of the file. - - `BetaLocalEnvironment object { type, skills }` + - `index: number` - - `BetaContainerReference object { container_id, type }` + 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 shell call. One of `in_progress`, `completed`, or `incomplete`. + 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` - - `ShellCallOutput object { call_id, output, type, 5 more }` + - `bytes: array of number` - The streamed output items emitted by a shell tool call. + - `logprob: number` - - `call_id: string` + - `top_logprobs: array of object { token, bytes, logprob }` - The unique ID of the shell tool call generated by the model. + - `token: string` - - `output: array of BetaResponseFunctionShellCallOutputContent` + - `bytes: array of number` - Captured chunks of stdout and stderr output, along with their associated outcomes. + - `logprob: number` - - `outcome: object { type } or object { exit_code, type }` + - `text: string` - The exit or timeout outcome associated with this shell call. + The text output from the model. - - `Timeout object { type }` + - `type: "output_text"` - Indicates that the shell call exceeded its configured time limit. + The type of the output text. Always `output_text`. - - `type: "timeout"` + - `"output_text"` - The outcome type. Always `timeout`. + - `BetaResponseOutputRefusal object { refusal, type }` - - `"timeout"` + A refusal from the model. - - `Exit object { exit_code, type }` + - `refusal: string` - Indicates that the shell commands finished and returned an exit code. + The refusal explanation from the model. - - `exit_code: number` + - `type: "refusal"` - The exit code returned by the shell process. + The type of the refusal. Always `refusal`. - - `type: "exit"` + - `"refusal"` - The outcome type. Always `exit`. + - `role: "assistant"` - - `"exit"` + The role of the output message. Always `assistant`. - - `stderr: string` + - `"assistant"` - Captured stderr output for the shell call. + - `status: "in_progress" or "completed" or "incomplete"` - - `stdout: string` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - Captured stdout output for the shell call. + - `"in_progress"` - - `type: "shell_call_output"` + - `"completed"` - The type of the item. Always `shell_call_output`. + - `"incomplete"` - - `"shell_call_output"` + - `type: "message"` - - `id: optional string` + The type of the output message. Always `message`. - The unique ID of the shell tool call output. Populated when this item is returned via API. + - `"message"` - `agent: optional object { agent_name }` @@ -148410,593 +146872,620 @@ 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 }` + - `phase: optional "commentary" or "final_answer"` - The execution context that produced this tool call. + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - `Direct object { type }` + - `"commentary"` - - `type: "direct"` + - `"final_answer"` - The caller type. Always `direct`. +### Beta Response Output Refusal - - `"direct"` +- `BetaResponseOutputRefusal object { refusal, type }` - - `Program object { caller_id, type }` + A refusal from the model. - - `caller_id: string` + - `refusal: string` - The call ID of the program item that produced this tool call. + The refusal explanation from the model. - - `type: "program"` + - `type: "refusal"` - The caller type. Always `program`. + The type of the refusal. Always `refusal`. - - `"program"` + - `"refusal"` - - `max_output_length: optional number` +### Beta Response Output Text - The maximum number of UTF-8 characters captured for this shell call's combined output. +- `BetaResponseOutputText object { annotations, logprobs, text, type }` - - `status: optional "in_progress" or "completed" or "incomplete"` + A text output from the model. - The status of the shell call output. + - `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 }` - - `"in_progress"` + The annotations of the text output. - - `"completed"` + - `FileCitation object { file_id, filename, index, type }` - - `"incomplete"` + A citation to a file. - - `ApplyPatchCall object { call_id, operation, status, 4 more }` + - `file_id: string` - A tool call representing a request to create, delete, or update files using diff patches. + The ID of the file. - - `call_id: string` + - `filename: string` - The unique ID of the apply patch tool call generated by the model. + The filename of the file cited. - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + - `index: number` - The specific create, delete, or update instruction for the apply_patch tool call. + The index of the file in the list of files. - - `CreateFile object { diff, path, type }` + - `type: "file_citation"` - Instruction for creating a new file via the apply_patch tool. + The type of the file citation. Always `file_citation`. - - `diff: string` + - `"file_citation"` - Unified diff content to apply when creating the file. + - `URLCitation object { end_index, start_index, title, 2 more }` - - `path: string` + A citation for a web resource used to generate a model response. - Path of the file to create relative to the workspace root. + - `end_index: number` - - `type: "create_file"` + The index of the last character of the URL citation in the message. - The operation type. Always `create_file`. + - `start_index: number` - - `"create_file"` + The index of the first character of the URL citation in the message. - - `DeleteFile object { path, type }` + - `title: string` - Instruction for deleting an existing file via the apply_patch tool. + The title of the web resource. - - `path: string` + - `type: "url_citation"` - Path of the file to delete relative to the workspace root. + The type of the URL citation. Always `url_citation`. - - `type: "delete_file"` + - `"url_citation"` - The operation type. Always `delete_file`. + - `url: string` - - `"delete_file"` + The URL of the web resource. - - `UpdateFile object { diff, path, type }` + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - Instruction for updating an existing file via the apply_patch tool. + A citation for a container file used to generate a model response. - - `diff: string` + - `container_id: string` - Unified diff content to apply to the existing file. + The ID of the container file. - - `path: string` + - `end_index: number` - Path of the file to update relative to the workspace root. + The index of the last character of the container file citation in the message. - - `type: "update_file"` + - `file_id: string` - The operation type. Always `update_file`. + The ID of the file. - - `"update_file"` + - `filename: string` - - `status: "in_progress" or "completed"` + The filename of the container file cited. - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `start_index: number` - - `"in_progress"` + The index of the first character of the container file citation in the message. - - `"completed"` + - `type: "container_file_citation"` - - `type: "apply_patch_call"` + The type of the container file citation. Always `container_file_citation`. - The type of the item. Always `apply_patch_call`. + - `"container_file_citation"` - - `"apply_patch_call"` + - `FilePath object { file_id, index, type }` - - `id: optional 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` - - `agent: optional object { agent_name }` + The ID of the file. - 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_path"` - - `caller: optional object { type } or object { caller_id, type }` + The type of the file path. Always `file_path`. - The execution context that produced this tool call. + - `"file_path"` - - `Direct object { type }` + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - - `type: "direct"` + - `token: string` - The caller type. Always `direct`. + - `bytes: array of number` - - `"direct"` + - `logprob: number` - - `Program object { caller_id, type }` + - `top_logprobs: array of object { token, bytes, logprob }` - - `caller_id: string` + - `token: string` - The call ID of the program item that produced this tool call. + - `bytes: array of number` - - `type: "program"` + - `logprob: number` - The caller type. Always `program`. + - `text: string` - - `"program"` + The text output from the model. - - `ApplyPatchCallOutput object { call_id, status, type, 4 more }` + - `type: "output_text"` - The streamed output emitted by an apply patch tool call. + The type of the output text. Always `output_text`. - - `call_id: string` + - `"output_text"` - The unique ID of the apply patch tool call generated by the model. +### Beta Response Output Text Annotation Added Event - - `status: "completed" or "failed"` +- `BetaResponseOutputTextAnnotationAddedEvent object { annotation, annotation_index, content_index, 5 more }` - The status of the apply patch tool call output. One of `completed` or `failed`. + Emitted when an annotation is added to output text content. - - `"completed"` + - `annotation: unknown` - - `"failed"` + The annotation object being added. (See annotation schema for details.) - - `type: "apply_patch_call_output"` + - `annotation_index: number` - The type of the item. Always `apply_patch_call_output`. + The index of the annotation within the content part. - - `"apply_patch_call_output"` + - `content_index: number` - - `id: optional string` + The index of the content part within the output item. - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `item_id: string` - - `agent: optional object { agent_name }` + The unique identifier of the item to which the annotation is being added. - The agent that produced this item. + - `output_index: number` - - `agent_name: string` + The index of the output item in the response's output array. - The canonical name of the agent that produced this item. + - `sequence_number: number` - - `caller: optional object { type } or object { caller_id, type }` + The sequence number of this event. - The execution context that produced this tool call. + - `type: "response.output_text.annotation.added"` - - `Direct object { type }` + The type of the event. Always 'response.output_text.annotation.added'. - - `type: "direct"` + - `"response.output_text.annotation.added"` - The caller type. Always `direct`. + - `agent: optional object { agent_name }` - - `"direct"` + The agent that owns this multi-agent streaming event. - - `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. +### Beta Response Prompt - - `type: "program"` +- `BetaResponsePrompt object { id, variables, version }` - The caller type. Always `program`. + Reference to a prompt template and its variables. + [Learn more](/docs/guides/text?api-mode=responses#reusable-prompts). - - `"program"` + - `id: string` - - `output: optional string` + The unique identifier of the prompt template to use. - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` - - `McpListTools object { id, server_label, tools, 3 more }` + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. - A list of tools available on an MCP server. + - `string` - - `id: string` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - The unique ID of the list. + A text input to the model. - - `server_label: string` + - `text: string` - The label of the MCP server. + The text input to the model. - - `tools: array of object { input_schema, name, annotations, description }` + - `type: "input_text"` - The tools available on the server. + The type of the input item. Always `input_text`. - - `input_schema: unknown` + - `"input_text"` - The JSON schema describing the tool's input. + - `prompt_cache_breakpoint: optional object { mode }` - - `name: string` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The name of the tool. + - `mode: "explicit"` - - `annotations: optional unknown` + The breakpoint mode. Always `explicit`. - Additional annotations about the tool. + - `"explicit"` - - `description: optional string` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - The description of the tool. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `type: "mcp_list_tools"` + - `detail: "low" or "high" or "auto" or "original"` - The type of the item. Always `mcp_list_tools`. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `"mcp_list_tools"` + - `"low"` - - `agent: optional object { agent_name }` + - `"high"` - The agent that produced this item. + - `"auto"` - - `agent_name: string` + - `"original"` - The canonical name of the agent that produced this item. + - `type: "input_image"` - - `error: optional string` + The type of the input item. Always `input_image`. - Error message if the server could not list tools. + - `"input_image"` - - `McpApprovalRequest object { id, arguments, name, 3 more }` + - `file_id: optional string` - A request for human approval of a tool invocation. + The ID of the file to be sent to the model. - - `id: string` + - `image_url: optional string` - The unique ID of the approval request. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `arguments: string` + - `prompt_cache_breakpoint: optional object { mode }` - A JSON string of arguments for 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 to run. + The breakpoint mode. Always `explicit`. - - `server_label: string` + - `"explicit"` - The label of the MCP server making the request. + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `type: "mcp_approval_request"` + A file input to the model. - The type of the item. Always `mcp_approval_request`. + - `type: "input_file"` - - `"mcp_approval_request"` + The type of the input item. Always `input_file`. - - `agent: optional object { agent_name }` + - `"input_file"` - The agent that produced this item. + - `detail: optional "auto" or "low" or "high"` - - `agent_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 canonical name of the agent that produced this item. + - `"auto"` - - `McpApprovalResponse object { approval_request_id, approve, type, 3 more }` + - `"low"` - A response to an MCP approval request. + - `"high"` - - `approval_request_id: string` + - `file_data: optional string` - The ID of the approval request being answered. + The content of the file to be sent to the model. - - `approve: boolean` + - `file_id: optional string` - Whether the request was approved. + The ID of the file to be sent to the model. - - `type: "mcp_approval_response"` + - `file_url: optional string` - The type of the item. Always `mcp_approval_response`. + The URL of the file to be sent to the model. - - `"mcp_approval_response"` + - `filename: optional string` - - `id: optional string` + The name of the file to be sent to the model. - The unique ID of the approval response + - `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"` - - `reason: optional string` + - `version: optional string` - Optional reason for the decision. + Optional version of the prompt template. - - `McpCall object { id, arguments, name, 7 more }` +### Beta Response Queued Event - An invocation of a tool on an MCP server. +- `BetaResponseQueuedEvent object { response, sequence_number, type, agent }` + + Emitted when a response is queued and waiting to be processed. + + - `response: BetaResponse` + + The full response object that is queued. - `id: string` - The unique ID of the tool call. + Unique identifier for this Response. - - `arguments: string` + - `created_at: number` - A JSON string of the arguments passed to the tool. + Unix timestamp (in seconds) of when this Response was created. - - `name: string` + - `error: BetaResponseError` - The name of the tool that was run. + An error object returned when the model fails to generate a Response. - - `server_label: string` + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 16 more` - The label of the MCP server running the tool. + The error code for the response. - - `type: "mcp_call"` + - `"server_error"` - The type of the item. Always `mcp_call`. + - `"rate_limit_exceeded"` - - `"mcp_call"` + - `"invalid_prompt"` - - `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"` - - `approval_request_id: optional string` + - `"invalid_base64_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. + - `"invalid_image_url"` - - `error: optional string` + - `"image_too_large"` - The error from the tool call, if any. + - `"image_too_small"` - - `output: optional string` + - `"image_parse_error"` - The output from the tool call. + - `"image_content_policy_violation"` - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `"invalid_image_mode"` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `"image_file_too_large"` - - `"in_progress"` + - `"unsupported_image_media_type"` - - `"completed"` + - `"empty_image_file"` - - `"incomplete"` + - `"failed_to_download_image"` - - `"calling"` + - `"image_file_not_found"` - - `"failed"` + - `message: string` - - `CustomToolCallOutput object { call_id, output, type, 3 more }` + A human-readable description of the error. - The output of a custom tool call from your code, being sent back to the model. + - `incomplete_details: object { reason }` - - `call_id: string` + Details about why the response is incomplete. - The call ID, used to map this custom tool call output to a custom tool call. + - `reason: optional "max_output_tokens" or "content_filter"` - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + The reason why the response is incomplete. - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `"max_output_tokens"` - - `StringOutput = string` + - `"content_filter"` - A string of the output of the custom tool call. + - `instructions: string or array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + A system (or developer) message inserted into the model's context. - Text, image, or file output of the custom tool 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. - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `string` - A text input to the model. + A text input to the model, equivalent to a text input with the + `developer` role. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `InputItemList = array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + A list of one or many input items to the model, containing + different content types. - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `BetaEasyInputMessage object { content, role, phase, type }` - A file input to the model. + 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: "custom_tool_call_output"` + - `content: string or BetaResponseInputMessageContentList` - The type of the custom tool call output. Always `custom_tool_call_output`. + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `"custom_tool_call_output"` + - `TextInput = string` - - `id: optional string` + A text input to the model. - The unique ID of the custom tool call output in the OpenAI platform. + - `BetaResponseInputMessageContentList = array of BetaResponseInputContent` - - `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"` - The caller type. Always `direct`. + - `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. - - `Program object { caller_id, type }` + - `mode: "explicit"` - - `caller_id: string` + The breakpoint mode. Always `explicit`. - The call ID of the program item that produced this tool call. + - `"explicit"` - - `type: "program"` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - The caller type. Always `program`. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `"program"` + - `detail: "low" or "high" or "auto" or "original"` - - `CustomToolCall object { call_id, input, name, 5 more }` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - A call to a custom tool created by the model. + - `"low"` - - `call_id: string` + - `"high"` - An identifier used to map this custom tool call to a tool call output. + - `"auto"` - - `input: string` + - `"original"` - The input for the custom tool call generated by the model. + - `type: "input_image"` - - `name: string` + The type of the input item. Always `input_image`. - The name of the custom tool being called. + - `"input_image"` - - `type: "custom_tool_call"` + - `file_id: optional string` - The type of the custom tool call. Always `custom_tool_call`. + The ID of the file to be sent to the model. - - `"custom_tool_call"` + - `image_url: optional string` - - `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 custom tool call in the OpenAI platform. + - `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"` - - `namespace: optional string` + - `file_data: optional string` - The namespace of the custom tool being called. + The content of the file to be sent to the model. - - `CompactionTrigger object { type, agent }` + - `file_id: optional string` - Compacts the current context. Must be the final input item. + The ID of the file to be sent to the model. - - `type: "compaction_trigger"` + - `file_url: optional string` - The type of the item. Always `compaction_trigger`. + The URL of the file to be sent to the model. - - `"compaction_trigger"` + - `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"` - - `ItemReference object { id, agent, type }` + The breakpoint mode. Always `explicit`. - An internal identifier for an item to reference. + - `"explicit"` - - `id: string` + - `role: "user" or "assistant" or "system" or "developer"` - The ID of the item to reference. + 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"` - - `type: optional "item_reference"` + - `phase: optional "commentary" or "final_answer"` - The type of item to reference. Always `item_reference`. + 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. - - `"item_reference"` + - `"commentary"` - - `Program object { id, call_id, code, 3 more }` + - `"final_answer"` - - `id: string` + - `type: optional "message"` - The unique ID of this program item. + The type of the message input. Always `message`. - - `call_id: string` + - `"message"` - The stable call ID of the program item. + - `Message object { content, role, agent, 2 more }` - - `code: 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 JavaScript source executed by programmatic tool calling. + - `content: BetaResponseInputMessageContentList` + + A list of one or many input items to the model, containing different content + types. - - `fingerprint: string` + - `role: "user" or "system" or "developer"` - Opaque program replay fingerprint that must be round-tripped. + The role of the message input. One of `user`, `system`, or `developer`. - - `type: "program"` + - `"user"` - The item type. Always `program`. + - `"system"` - - `"program"` + - `"developer"` - `agent: optional object { agent_name }` @@ -149006,620 +147495,638 @@ 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 }` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `id: string` + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The unique ID of this program output item. + - `"in_progress"` - - `call_id: string` + - `"completed"` - The call ID of the program item. + - `"incomplete"` - - `result: string` + - `type: optional "message"` - The result produced by the program item. + The type of the message input. Always set to `message`. - - `status: "completed" or "incomplete"` + - `"message"` - The terminal status of the program output. + - `BetaResponseOutputMessage object { id, content, role, 4 more }` - - `"completed"` + An output message from the model. - - `"incomplete"` + - `id: string` - - `type: "program_output"` + The unique ID of the output message. - The item type. Always `program_output`. + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - - `"program_output"` + The content of the output message. - - `agent: optional object { agent_name }` + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - The agent that produced this item. + A text output from the model. - - `agent_name: 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 canonical name of the agent that produced this item. + The annotations of the text output. -### Beta Response Input Audio + - `FileCitation object { file_id, filename, index, type }` -- `BetaResponseInputAudio object { input_audio, type }` + A citation to a file. - An audio input to the model. + - `file_id: string` - - `input_audio: object { data, format }` + The ID of the file. - - `data: string` + - `filename: string` - Base64-encoded audio data. + The filename of the file cited. - - `format: "mp3" or "wav"` + - `index: number` - The format of the audio data. Currently supported formats are `mp3` and - `wav`. + The index of the file in the list of files. - - `"mp3"` + - `type: "file_citation"` - - `"wav"` + The type of the file citation. Always `file_citation`. - - `type: "input_audio"` + - `"file_citation"` - The type of the input item. Always `input_audio`. + - `URLCitation object { end_index, start_index, title, 2 more }` - - `"input_audio"` + A citation for a web resource used to generate a model response. -### Beta Response Input Content + - `end_index: number` -- `BetaResponseInputContent = BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + The index of the last character of the URL citation in the message. - A text input to the model. + - `start_index: number` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + The index of the first character of the URL citation in the message. - A text input to the model. + - `title: string` - - `text: string` + The title of the web resource. - The text input to the model. + - `type: "url_citation"` - - `type: "input_text"` + The type of the URL citation. Always `url_citation`. - The type of the input item. Always `input_text`. + - `"url_citation"` - - `"input_text"` + - `url: string` - - `prompt_cache_breakpoint: optional object { mode }` + The URL of the web resource. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - - `mode: "explicit"` + A citation for a container file used to generate a model response. - The breakpoint mode. Always `explicit`. + - `container_id: string` - - `"explicit"` + The ID of the container file. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `end_index: number` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The index of the last character of the container file citation in the message. - - `detail: "low" or "high" or "auto" or "original"` + - `file_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 ID of the file. - - `"low"` + - `filename: string` - - `"high"` + The filename of the container file cited. - - `"auto"` + - `start_index: number` - - `"original"` + The index of the first character of the container file citation in the message. - - `type: "input_image"` + - `type: "container_file_citation"` - The type of the input item. Always `input_image`. + The type of the container file citation. Always `container_file_citation`. - - `"input_image"` + - `"container_file_citation"` - - `file_id: optional string` + - `FilePath object { file_id, index, type }` - The ID of the file to be sent to the model. + A path to a file. - - `image_url: optional string` + - `file_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 ID of the file. - - `prompt_cache_breakpoint: optional object { mode }` + - `index: 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 index of the file in the list of files. - - `mode: "explicit"` + - `type: "file_path"` - The breakpoint mode. Always `explicit`. + The type of the file path. Always `file_path`. - - `"explicit"` + - `"file_path"` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - A file input to the model. + - `token: string` - - `type: "input_file"` + - `bytes: array of number` - The type of the input item. Always `input_file`. + - `logprob: number` - - `"input_file"` + - `top_logprobs: array of object { token, bytes, logprob }` - - `detail: optional "auto" or "low" or "high"` + - `token: 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`. + - `bytes: array of number` - - `"auto"` + - `logprob: number` - - `"low"` + - `text: string` - - `"high"` + The text output from the model. - - `file_data: optional string` + - `type: "output_text"` - The content of the file to be sent to the model. + The type of the output text. Always `output_text`. - - `file_id: optional string` + - `"output_text"` - The ID of the file to be sent to the model. + - `BetaResponseOutputRefusal object { refusal, type }` - - `file_url: optional string` + A refusal from the model. - The URL of the file to be sent to the model. + - `refusal: string` - - `filename: optional string` + The refusal explanation from the model. - The name of the file to be sent to the model. + - `type: "refusal"` - - `prompt_cache_breakpoint: optional object { mode }` + The type of the refusal. Always `refusal`. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `"refusal"` - - `mode: "explicit"` + - `role: "assistant"` - The breakpoint mode. Always `explicit`. + The role of the output message. Always `assistant`. - - `"explicit"` + - `"assistant"` -### Beta Response Input File + - `status: "in_progress" or "completed" or "incomplete"` -- `BetaResponseInputFile object { type, detail, file_data, 4 more }` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - A file input to the model. + - `"in_progress"` - - `type: "input_file"` + - `"completed"` - The type of the input item. Always `input_file`. + - `"incomplete"` - - `"input_file"` + - `type: "message"` - - `detail: optional "auto" or "low" or "high"` + The type of the output message. Always `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`. + - `"message"` - - `"auto"` + - `agent: optional object { agent_name }` - - `"low"` + The agent that produced this item. - - `"high"` + - `agent_name: string` - - `file_data: optional string` + The canonical name of the agent that produced this item. - The content of the file to be sent to the model. + - `phase: optional "commentary" or "final_answer"` - - `file_id: 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 ID of the file to be sent to the model. + - `"commentary"` - - `file_url: optional string` + - `"final_answer"` - The URL of the file to be sent to the model. + - `FileSearchCall object { id, queries, status, 3 more }` - - `filename: optional string` + The results of a file search tool call. See the + [file search guide](/docs/guides/tools-file-search) for more information. - The name of the file to be sent to the model. + - `id: string` - - `prompt_cache_breakpoint: optional object { mode }` + The unique ID of the file search 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. + - `queries: array of string` - - `mode: "explicit"` + The queries used to search for files. - The breakpoint mode. Always `explicit`. + - `status: "in_progress" or "searching" or "completed" or 2 more` - - `"explicit"` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, -### Beta Response Input File Content + - `"in_progress"` -- `BetaResponseInputFileContent object { type, detail, file_data, 4 more }` + - `"searching"` - A file input to the model. + - `"completed"` - - `type: "input_file"` + - `"incomplete"` - The type of the input item. Always `input_file`. + - `"failed"` - - `"input_file"` + - `type: "file_search_call"` - - `detail: optional "auto" or "low" or "high"` + The type of the file search tool call. Always `file_search_call`. - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `"file_search_call"` - - `"auto"` + - `agent: optional object { agent_name }` - - `"low"` + The agent that produced this item. - - `"high"` + - `agent_name: string` - - `file_data: optional string` + The canonical name of the agent that produced this item. - The base64-encoded data of the file to be sent to the model. + - `results: optional array of object { attributes, file_id, filename, 2 more }` - - `file_id: optional string` + The results of the file search tool call. - The ID of the file to be sent to the model. + - `attributes: optional map[string or number or boolean]` - - `file_url: 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 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. + - `boolean` - - `prompt_cache_breakpoint: optional object { mode }` + - `file_id: optional string` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The unique ID of the file. - - `mode: "explicit"` + - `filename: optional string` - The breakpoint mode. Always `explicit`. + The name of the file. - - `"explicit"` + - `score: optional number` -### Beta Response Input Image + The relevance score of the file - a value between 0 and 1. -- `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `text: optional string` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The text that was retrieved from the file. - - `detail: "low" or "high" or "auto" or "original"` + - `ComputerCall object { id, call_id, pending_safety_checks, 5 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 call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - - `"low"` + - `id: string` - - `"high"` + The unique ID of the computer call. - - `"auto"` + - `call_id: string` - - `"original"` + An identifier used when responding to the tool call with output. - - `type: "input_image"` + - `pending_safety_checks: array of object { id, code, message }` - The type of the input item. Always `input_image`. + The pending safety checks for the computer call. - - `"input_image"` + - `id: string` - - `file_id: optional string` + The ID of the pending safety check. - The ID of the file to be sent to the model. + - `code: optional string` - - `image_url: optional string` + The type of the pending safety check. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `message: optional string` - - `prompt_cache_breakpoint: optional object { mode }` + Details about the pending safety check. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `status: "in_progress" or "completed" or "incomplete"` - - `mode: "explicit"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The breakpoint mode. Always `explicit`. + - `"in_progress"` - - `"explicit"` + - `"completed"` -### Beta Response Input Image Content + - `"incomplete"` -- `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` + - `type: "computer_call"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + The type of the computer call. Always `computer_call`. - - `type: "input_image"` + - `"computer_call"` - The type of the input item. Always `input_image`. + - `action: optional BetaComputerAction` - - `"input_image"` + A click action. - - `detail: optional "low" or "high" or "auto" or "original"` + - `Click object { button, type, x, 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 click action. - - `"low"` + - `button: "left" or "right" or "wheel" or 2 more` - - `"high"` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `"auto"` + - `"left"` - - `"original"` + - `"right"` - - `file_id: optional string` + - `"wheel"` - The ID of the file to be sent to the model. + - `"back"` - - `image_url: optional string` + - `"forward"` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `type: "click"` - - `prompt_cache_breakpoint: optional object { mode }` + Specifies the event type. For a click action, this property is always `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. + - `"click"` - - `mode: "explicit"` + - `x: number` - The breakpoint mode. Always `explicit`. + The x-coordinate where the click occurred. - - `"explicit"` + - `y: number` -### Beta Response Input Message Content List + The y-coordinate where the click occurred. -- `BetaResponseInputMessageContentList = array of BetaResponseInputContent` + - `keys: optional array of string` - A list of one or many input items to the model, containing different content - types. + The keys being held while clicking. - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `DoubleClick object { keys, type, x, y }` - A text input to the model. + A double click action. - - `text: string` + - `keys: array of string` - The text input to the model. + The keys being held while double-clicking. - - `type: "input_text"` + - `type: "double_click"` - The type of the input item. Always `input_text`. + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `"input_text"` + - `"double_click"` - - `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 where the double click occurred. - - `mode: "explicit"` + - `y: number` - The breakpoint mode. Always `explicit`. + The y-coordinate where the double click occurred. - - `"explicit"` + - `Drag object { path, type, keys }` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + A drag action. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `path: array of object { x, y }` - - `detail: "low" or "high" or "auto" or "original"` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `"low"` + - `x: number` - - `"high"` + The x-coordinate. - - `"auto"` + - `y: number` - - `"original"` + The y-coordinate. - - `type: "input_image"` + - `type: "drag"` - The type of the input item. Always `input_image`. + Specifies the event type. For a drag action, this property is always set to `drag`. - - `"input_image"` + - `"drag"` - - `file_id: optional string` + - `keys: optional array of string` - The ID of the file to be sent to the model. + The keys being held while dragging the mouse. - - `image_url: optional string` + - `Keypress object { keys, type }` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + A collection of keypresses the model would like to perform. - - `prompt_cache_breakpoint: optional object { mode }` + - `keys: 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 combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `mode: "explicit"` + - `type: "keypress"` - The breakpoint mode. Always `explicit`. + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `"explicit"` + - `"keypress"` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `Move object { type, x, y, keys }` - A file input to the model. + A mouse move action. - - `type: "input_file"` + - `type: "move"` - The type of the input item. Always `input_file`. + Specifies the event type. For a move action, this property is always set to `move`. - - `"input_file"` + - `"move"` - - `detail: optional "auto" or "low" or "high"` + - `x: 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 x-coordinate to move to. - - `"auto"` + - `y: number` - - `"low"` + The y-coordinate to move to. - - `"high"` + - `keys: optional array of string` - - `file_data: optional string` + The keys being held while moving the mouse. - The content of the file to be sent to the model. + - `Screenshot object { type }` - - `file_id: optional string` + A screenshot action. - The ID of the file to be sent to the model. + - `type: "screenshot"` - - `file_url: optional string` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - The URL of the file to be sent to the model. + - `"screenshot"` - - `filename: optional string` + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - The name of the file to be sent to the model. + A scroll action. - - `prompt_cache_breakpoint: optional object { mode }` + - `scroll_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 horizontal scroll distance. - - `mode: "explicit"` + - `scroll_y: number` - The breakpoint mode. Always `explicit`. + The vertical scroll distance. - - `"explicit"` + - `type: "scroll"` -### Beta Response Input Message Item + Specifies the event type. For a scroll action, this property is always set to `scroll`. -- `BetaResponseInputMessageItem object { id, content, role, 3 more }` + - `"scroll"` - - `id: string` + - `x: number` - The unique ID of the message input. + The x-coordinate where the scroll occurred. - - `content: BetaResponseInputMessageContentList` + - `y: number` - A list of one or many input items to the model, containing different content - types. + The y-coordinate where the scroll occurred. - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `keys: optional array of string` - A text input to the model. + The keys being held while scrolling. - - `text: string` + - `Type object { text, type }` - The text input to the model. + An action to type in text. - - `type: "input_text"` + - `text: string` - The type of the input item. Always `input_text`. + The text to type. - - `"input_text"` + - `type: "type"` - - `prompt_cache_breakpoint: optional object { mode }` + Specifies the event type. For a type action, this property is always set to `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"` - - `mode: "explicit"` + - `Wait object { type }` - The breakpoint mode. Always `explicit`. + A wait action. - - `"explicit"` + - `type: "wait"` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + Specifies the event type. For a wait action, this property is always set to `wait`. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `"wait"` - - `detail: "low" or "high" or "auto" or "original"` + - `actions: optional BetaComputerActionList` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `"low"` + - `Click object { button, type, x, 2 more }` - - `"high"` + A click action. - - `"auto"` + - `DoubleClick object { keys, type, x, y }` - - `"original"` + A double click action. - - `type: "input_image"` + - `Drag object { path, type, keys }` - The type of the input item. Always `input_image`. + A drag action. - - `"input_image"` + - `Keypress object { keys, type }` - - `file_id: optional string` + A collection of keypresses the model would like to perform. - The ID of the file to be sent to the model. + - `Move object { type, x, y, keys }` - - `image_url: optional string` + A mouse move action. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `Screenshot object { type }` - - `prompt_cache_breakpoint: optional object { mode }` + A screenshot action. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - - `mode: "explicit"` + A scroll action. - The breakpoint mode. Always `explicit`. + - `Type object { text, type }` - - `"explicit"` + An action to type in text. - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `Wait object { type }` - A file input to the model. + A wait action. - - `type: "input_file"` + - `agent: optional object { agent_name }` - The type of the input item. Always `input_file`. + The agent that produced this item. - - `"input_file"` + - `agent_name: string` - - `detail: optional "auto" or "low" or "high"` + The canonical name of 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`. + - `ComputerCallOutput object { call_id, output, type, 4 more }` - - `"auto"` + The output of a computer tool call. - - `"low"` + - `call_id: string` - - `"high"` + The ID of the computer tool call that produced the output. - - `file_data: optional string` + - `output: BetaResponseComputerToolCallOutputScreenshot` - The content of the file to be sent to the model. + A computer screenshot image used with the computer use tool. - - `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`. - - `file_url: optional string` + - `"computer_screenshot"` - The URL of the file to be sent to the model. + - `file_id: optional string` - - `filename: optional string` + The identifier of an uploaded file that contains the screenshot. - The name of the file to be sent to the model. + - `image_url: optional string` - - `prompt_cache_breakpoint: optional object { mode }` + The URL of the screenshot 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. + - `type: "computer_call_output"` - - `mode: "explicit"` + The type of the computer tool call output. Always `computer_call_output`. - The breakpoint mode. Always `explicit`. + - `"computer_call_output"` - - `"explicit"` + - `id: optional string` - - `role: "user" or "system" or "developer"` + The ID of the computer tool call output. - The role of the message input. One of `user`, `system`, or `developer`. + - `acknowledged_safety_checks: optional array of object { id, code, message }` - - `"user"` + The safety checks reported by the API that have been acknowledged by the developer. - - `"system"` + - `id: string` - - `"developer"` + The ID of the pending safety check. - - `type: "message"` + - `code: optional string` - The type of the message input. Always set to `message`. + The type of the pending safety check. - - `"message"` + - `message: optional string` + + Details about the pending safety check. - `agent: optional object { agent_name }` @@ -149631,8 +148138,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `status: optional "in_progress" or "completed" or "incomplete"` - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - `"in_progress"` @@ -149640,590 +148146,583 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"incomplete"` -### Beta Response Input Text + - `WebSearchCall object { id, action, status, 2 more }` -- `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. - A text input to the model. + - `id: string` - - `text: string` + The unique ID of the web search tool call. - The text input to the model. + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - - `type: "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). - The type of the input item. Always `input_text`. + - `Search object { type, queries, query, sources }` - - `"input_text"` + Action type "search" - Performs a web search query. - - `prompt_cache_breakpoint: optional object { mode }` + - `type: "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. + The action type. - - `mode: "explicit"` + - `"search"` - The breakpoint mode. Always `explicit`. + - `queries: optional array of string` - - `"explicit"` + The search queries. -### Beta Response Input Text Content + - `query: optional string` -- `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` + The search query. - A text input to the model. + - `sources: optional array of object { type, url }` - - `text: string` + The sources used in the search. - The text input to the model. + - `type: "url"` - - `type: "input_text"` + The type of source. Always `url`. - The type of the input item. Always `input_text`. + - `"url"` - - `"input_text"` + - `url: string` - - `prompt_cache_breakpoint: optional object { mode }` + The URL of the source. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `OpenPage object { type, url }` - - `mode: "explicit"` + Action type "open_page" - Opens a specific URL from search results. - The breakpoint mode. Always `explicit`. + - `type: "open_page"` - - `"explicit"` + The action type. -### Beta Response Local Environment + - `"open_page"` -- `BetaResponseLocalEnvironment object { type }` + - `url: optional string` - Represents the use of a local environment to perform shell actions. + The URL opened by the model. - - `type: "local"` + - `FindInPage object { pattern, type, url }` - The environment type. Always `local`. + Action type "find_in_page": Searches for a pattern within a loaded page. - - `"local"` + - `pattern: string` -### Beta Response Mcp Call Arguments Delta Event + The pattern or text to search for within the page. -- `BetaResponseMcpCallArgumentsDeltaEvent object { delta, item_id, output_index, 3 more }` + - `type: "find_in_page"` - Emitted when there is a delta (partial update) to the arguments of an MCP tool call. + The action type. - - `delta: string` + - `"find_in_page"` - A JSON string containing the partial update to the arguments for the MCP tool call. + - `url: string` - - `item_id: string` + The URL of the page searched for the pattern. - The unique identifier of the MCP tool call item being processed. + - `status: "in_progress" or "searching" or "completed" or "failed"` - - `output_index: number` + The status of the web search tool call. - The index of the output item in the response's output array. + - `"in_progress"` - - `sequence_number: number` + - `"searching"` - The sequence number of this event. + - `"completed"` - - `type: "response.mcp_call_arguments.delta"` + - `"failed"` - The type of the event. Always 'response.mcp_call_arguments.delta'. + - `type: "web_search_call"` - - `"response.mcp_call_arguments.delta"` + The type of the web search tool call. Always `web_search_call`. + + - `"web_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 Mcp Call Arguments Done Event - -- `BetaResponseMcpCallArgumentsDoneEvent object { arguments, item_id, output_index, 3 more }` + - `FunctionCall object { arguments, call_id, name, 6 more }` - Emitted when the arguments for an MCP tool call are finalized. + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. - `arguments: string` - A JSON string containing the finalized arguments for the MCP tool call. + A JSON string of the arguments to pass to the function. - - `item_id: string` + - `call_id: string` - The unique identifier of the MCP tool call item being processed. + 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.mcp_call_arguments.done"` + - `"function_call"` - The type of the event. Always 'response.mcp_call_arguments.done'. + - `id: optional string` - - `"response.mcp_call_arguments.done"` + 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. -### Beta Response Mcp Call Completed Event - -- `BetaResponseMcpCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` - - Emitted when an MCP tool call has completed successfully. - - - `item_id: string` - - The ID of the MCP tool call item that completed. - - - `output_index: number` + - `caller: optional object { type } or object { caller_id, type }` - The index of the output item that completed. + The execution context that produced this tool call. - - `sequence_number: number` + - `Direct object { type }` - The sequence number of this event. + - `type: "direct"` - - `type: "response.mcp_call.completed"` + - `"direct"` - The type of the event. Always 'response.mcp_call.completed'. + - `Program object { caller_id, type }` - - `"response.mcp_call.completed"` + - `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` + - `"program"` - The canonical name of the agent that produced this item. + - `namespace: optional string` -### Beta Response Mcp Call Failed Event + The namespace of the function to run. -- `BetaResponseMcpCallFailedEvent object { item_id, output_index, sequence_number, 2 more }` + - `status: optional "in_progress" or "completed" or "incomplete"` - Emitted when an MCP tool call has failed. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `item_id: string` + - `"in_progress"` - The ID of the MCP tool call item that failed. + - `"completed"` - - `output_index: number` + - `"incomplete"` - The index of the output item that failed. + - `FunctionCallOutput object { call_id, output, type, 4 more }` - - `sequence_number: number` + The output of a function tool call. - The sequence number of this event. + - `call_id: string` - - `type: "response.mcp_call.failed"` + The unique ID of the function tool call generated by the model. - The type of the event. Always 'response.mcp_call.failed'. + - `output: string or array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` - - `"response.mcp_call.failed"` + Text, image, or file output of the function tool call. - - `agent: optional object { agent_name }` + - `string` - The agent that owns this multi-agent streaming event. + A JSON string of the output of the function tool call. - - `agent_name: string` + - `array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` - The canonical name of the agent that produced this item. + An array of content outputs (text, image, file) for the function tool call. -### Beta Response Mcp Call In Progress Event + - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` -- `BetaResponseMcpCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` + A text input to the model. - Emitted when an MCP tool call is in progress. + - `text: string` - - `item_id: string` + The text input to the model. - The unique identifier of the MCP tool call item being processed. + - `type: "input_text"` - - `output_index: number` + The type of the input item. Always `input_text`. - The index of the output item in the response's output array. + - `"input_text"` - - `sequence_number: number` + - `prompt_cache_breakpoint: optional object { mode }` - The sequence number of this event. + Marks the exact end of a reusable 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: "response.mcp_call.in_progress"` + - `mode: "explicit"` - The type of the event. Always 'response.mcp_call.in_progress'. + The breakpoint mode. Always `explicit`. - - `"response.mcp_call.in_progress"` + - `"explicit"` - - `agent: optional object { agent_name }` + - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` - The agent that owns this multi-agent streaming event. + An image input to the model. Learn about [image inputs](/docs/guides/vision) - - `agent_name: string` + - `type: "input_image"` - The canonical name of the agent that produced this item. + The type of the input item. Always `input_image`. -### Beta Response Mcp List Tools Completed Event + - `"input_image"` -- `BetaResponseMcpListToolsCompletedEvent object { item_id, output_index, sequence_number, 2 more }` + - `detail: optional "low" or "high" or "auto" or "original"` - Emitted when the list of available MCP tools has been successfully retrieved. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `item_id: string` + - `"low"` - The ID of the MCP tool call item that produced this output. + - `"high"` - - `output_index: number` + - `"auto"` - The index of the output item that was processed. + - `"original"` - - `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.mcp_list_tools.completed"` + - `image_url: optional string` - The type of the event. Always 'response.mcp_list_tools.completed'. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `"response.mcp_list_tools.completed"` + - `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 Mcp List Tools Failed Event + - `BetaResponseInputFileContent object { type, detail, file_data, 4 more }` -- `BetaResponseMcpListToolsFailedEvent object { item_id, output_index, sequence_number, 2 more }` + A file input to the model. - Emitted when the attempt to list available MCP tools has failed. + - `type: "input_file"` - - `item_id: string` + The type of the input item. Always `input_file`. - The ID of the MCP tool call item that failed. + - `"input_file"` - - `output_index: number` + - `detail: optional "auto" or "low" or "high"` - The index of the output item that failed. + 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`. - - `sequence_number: number` + - `"auto"` - The sequence number of this event. + - `"low"` - - `type: "response.mcp_list_tools.failed"` + - `"high"` - The type of the event. Always 'response.mcp_list_tools.failed'. + - `file_data: optional string` - - `"response.mcp_list_tools.failed"` + The base64-encoded data of the file to be sent to the model. - - `agent: optional object { agent_name }` + - `file_id: optional string` - The agent that owns this multi-agent streaming event. + The ID of the file to be sent to the model. - - `agent_name: string` + - `file_url: optional string` - The canonical name of the agent that produced this item. + The URL of the file to be sent to the model. -### Beta Response Mcp List Tools In Progress Event + - `filename: optional string` -- `BetaResponseMcpListToolsInProgressEvent object { item_id, output_index, sequence_number, 2 more }` + The name of the file to be sent to the model. - Emitted when the system is in the process of retrieving the list of available MCP tools. + - `prompt_cache_breakpoint: optional object { mode }` - - `item_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 ID of the MCP tool call item that is being processed. + - `mode: "explicit"` - - `output_index: number` + The breakpoint mode. Always `explicit`. - The index of the output item that is being processed. + - `"explicit"` - - `sequence_number: number` + - `type: "function_call_output"` - The sequence number of this event. + The type of the function tool call output. Always `function_call_output`. - - `type: "response.mcp_list_tools.in_progress"` + - `"function_call_output"` - The type of the event. Always 'response.mcp_list_tools.in_progress'. + - `id: optional string` - - `"response.mcp_list_tools.in_progress"` + 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 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 + - `caller: optional object { type } or object { caller_id, type }` -- `BetaResponseOutputAudio object { data, transcript, type }` + The execution context that produced this tool call. - An audio output from the model. + - `Direct object { type }` - - `data: string` + - `type: "direct"` - Base64-encoded audio data from the model. + The caller type. Always `direct`. - - `transcript: string` + - `"direct"` - The transcript of the audio data from the model. + - `Program object { caller_id, type }` - - `type: "output_audio"` + - `caller_id: string` - The type of the output audio. Always `output_audio`. + The call ID of the program item that produced this tool call. - - `"output_audio"` + - `type: "program"` -### Beta Response Output Item + The caller type. Always `program`. -- `BetaResponseOutputItem = BetaResponseOutputMessage or object { id, queries, status, 3 more } or object { arguments, call_id, name, 6 more } or 28 more` + - `"program"` - An output message from the model. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `BetaResponseOutputMessage object { id, content, role, 4 more }` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - An output message from the model. + - `"in_progress"` - - `id: string` + - `"completed"` - The unique ID of the output message. + - `"incomplete"` - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + - `AgentMessage object { author, content, recipient, 3 more }` - The content of the output message. + A message routed between agents. - - `BetaResponseOutputText object { annotations, text, type, logprobs }` + - `author: string` - A text output from the model. + The sending agent identity. - - `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 }` + - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` - The annotations of the text output. + Plaintext, image, or encrypted content sent between agents. - - `FileCitation object { file_id, filename, index, type }` + - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` - A citation to a file. + A text input to the model. - - `file_id: string` + - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` - The ID of the file. + An image input to the model. Learn about [image inputs](/docs/guides/vision) - - `filename: string` + - `EncryptedContent object { encrypted_content, type }` - The filename of the file cited. + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `index: number` + - `encrypted_content: string` - The index of the file in the list of files. + Opaque encrypted content. - - `type: "file_citation"` + - `type: "encrypted_content"` - The type of the file citation. Always `file_citation`. + The type of the input item. Always `encrypted_content`. - - `"file_citation"` + - `"encrypted_content"` - - `URLCitation object { end_index, start_index, title, 2 more }` + - `recipient: string` - A citation for a web resource used to generate a model response. + The destination agent identity. - - `end_index: number` + - `type: "agent_message"` + + The item type. Always `agent_message`. + + - `"agent_message"` - The index of the last character of the URL citation in the message. + - `id: optional string` - - `start_index: number` + The unique ID of this agent message item. - 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`. + - `MultiAgentCall object { action, arguments, call_id, 3 more }` - - `"url_citation"` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `url: string` + The multi-agent action that was executed. - The URL of the web resource. + - `"spawn_agent"` - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + - `"interrupt_agent"` - A citation for a container file used to generate a model response. + - `"list_agents"` - - `container_id: string` + - `"send_message"` - The ID of the container file. + - `"followup_task"` - - `end_index: number` + - `"wait_agent"` - The index of the last character of the container file citation in the message. + - `arguments: string` - - `file_id: string` + The action arguments as a JSON string. - The ID of the file. + - `call_id: string` - - `filename: string` + The unique ID linking this call to its output. - The filename of the container file cited. + - `type: "multi_agent_call"` - - `start_index: number` + The item type. Always `multi_agent_call`. - The index of the first character of the container file citation in the message. + - `"multi_agent_call"` - - `type: "container_file_citation"` + - `id: optional string` - The type of the container file citation. Always `container_file_citation`. + The unique ID of this multi-agent call. - - `"container_file_citation"` + - `agent: optional object { agent_name }` - - `FilePath object { file_id, index, type }` + The agent that produced this item. - A path to a file. + - `agent_name: string` - - `file_id: string` + The canonical name of the agent that produced this item. - The ID of the file. + - `MultiAgentCallOutput object { action, call_id, output, 3 more }` - - `index: number` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - The index of the file in the list of files. + The multi-agent action that produced this result. - - `type: "file_path"` + - `"spawn_agent"` - The type of the file path. Always `file_path`. + - `"interrupt_agent"` - - `"file_path"` + - `"list_agents"` - - `text: string` + - `"send_message"` - The text output from the model. + - `"followup_task"` - - `type: "output_text"` + - `"wait_agent"` - The type of the output text. Always `output_text`. + - `call_id: string` - - `"output_text"` + The unique ID of the multi-agent call. - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + - `output: array of object { text, type, annotations }` - - `token: string` + Text output returned by the multi-agent action. - - `bytes: array of number` + - `text: string` - - `logprob: number` + The text content. - - `top_logprobs: array of object { token, bytes, logprob }` + - `type: "output_text"` - - `token: string` + The content type. Always `output_text`. - - `bytes: array of number` + - `"output_text"` - - `logprob: number` + - `annotations: optional array of object { file_id, filename, index, type } or array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` - - `BetaResponseOutputRefusal object { refusal, type }` + Citations associated with the text content. - A refusal from the model. + - `array of object { file_id, filename, index, type }` - - `refusal: string` + - `file_id: string` - The refusal explanation from the model. + The ID of the file. - - `type: "refusal"` + - `filename: string` - The type of the refusal. Always `refusal`. + The filename of the file cited. - - `"refusal"` + - `index: number` - - `role: "assistant"` + The index of the file in the list of files. - The role of the output message. Always `assistant`. + - `type: "file_citation"` - - `"assistant"` + The citation type. Always `file_citation`. - - `status: "in_progress" or "completed" or "incomplete"` + - `"file_citation"` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `array of object { end_index, start_index, title, 2 more }` - - `"in_progress"` + - `end_index: number` - - `"completed"` + The index of the last character of the citation in the message. - - `"incomplete"` + - `start_index: number` - - `type: "message"` + The index of the first character of the citation in the message. - The type of the output message. Always `message`. + - `title: string` - - `"message"` + The title of the cited resource. - - `agent: optional object { agent_name }` + - `type: "url_citation"` - The agent that produced this item. + The citation type. Always `url_citation`. - - `agent_name: string` + - `"url_citation"` - The canonical name of the agent that produced this item. + - `url: string` - - `phase: optional "commentary" or "final_answer"` + The URL of the cited resource. - 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. + - `array of object { container_id, end_index, file_id, 3 more }` - - `"commentary"` + - `container_id: string` - - `"final_answer"` + The ID of the container. - - `FileSearchCall object { id, queries, status, 3 more }` + - `end_index: number` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + The index of the last character of the citation in the message. - - `id: string` + - `file_id: string` - The unique ID of the file search tool call. + The ID of the container file. - - `queries: array of string` + - `filename: string` - The queries used to search for files. + The filename of the container file cited. - - `status: "in_progress" or "searching" or "completed" or 2 more` + - `start_index: number` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + The index of the first character of the citation in the message. - - `"in_progress"` + - `type: "container_file_citation"` - - `"searching"` + The citation type. Always `container_file_citation`. - - `"completed"` + - `"container_file_citation"` - - `"incomplete"` + - `type: "multi_agent_call_output"` - - `"failed"` + The item type. Always `multi_agent_call_output`. - - `type: "file_search_call"` + - `"multi_agent_call_output"` - The type of the file search tool call. Always `file_search_call`. + - `id: optional string` - - `"file_search_call"` + The unique ID of this multi-agent call output. - `agent: optional object { agent_name }` @@ -150233,1187 +148732,1206 @@ 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. + - `ToolSearchCall object { arguments, type, id, 4 more }` - - `attributes: optional map[string or number or boolean]` + - `arguments: unknown` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. Keys are strings - with a maximum length of 64 characters. Values are strings with a maximum - length of 512 characters, booleans, or numbers. + The arguments supplied to the tool search call. - - `string` + - `type: "tool_search_call"` - - `number` + The item type. Always `tool_search_call`. - - `boolean` + - `"tool_search_call"` - - `file_id: optional string` + - `id: optional string` - The unique ID of the file. + The unique ID of this tool search call. - - `filename: optional string` + - `agent: optional object { agent_name }` - The name of the file. + The agent that produced this item. - - `score: optional number` + - `agent_name: string` - The relevance score of the file - a value between 0 and 1. + The canonical name of the agent that produced this item. - - `text: optional string` + - `call_id: optional string` - The text that was retrieved from the file. + The unique ID of the tool search call generated by the model. - - `FunctionCall object { arguments, call_id, name, 6 more }` + - `execution: optional "server" or "client"` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + Whether tool search was executed by the server or by the client. - - `arguments: string` + - `"server"` - A JSON string of the arguments to pass to the function. + - `"client"` - - `call_id: string` + - `status: optional "in_progress" or "completed" or "incomplete"` - The unique ID of the function tool call generated by the model. + The status of the tool search call. - - `name: string` + - `"in_progress"` - The name of the function to run. + - `"completed"` - - `type: "function_call"` + - `"incomplete"` - The type of the function tool call. Always `function_call`. + - `ToolSearchOutput object { tools, type, id, 4 more }` - - `"function_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` - - `id: optional string` + The loaded tool definitions returned by the tool search output. - The unique ID of the function tool 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"` - - `"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"` - - `"program"` + - `"programmatic"` - - `namespace: optional string` + - `defer_loading: optional boolean` - The namespace of the function to run. + Whether this function is deferred and loaded via tool search. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `description: optional string` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + 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 }` - - `FunctionCallOutput object { id, call_id, output, 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). - - `id: string` + - `type: "file_search"` - The unique ID of the function call tool output. + The type of the file search tool. Always `file_search`. - - `call_id: string` + - `"file_search"` - The unique ID of the function tool call generated by the model. + - `vector_store_ids: array of string` - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + The IDs of the vector stores to search. - The output from the function call generated by your code. - Can be a string or an list of output content. + - `filters: optional object { key, type, value } or object { filters, type }` - - `StringOutput = string` + A filter to apply. - A string of the output of the function call. + - `ComparisonFilter object { key, type, value }` - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - Text, image, or file output of the function call. + - `key: string` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + The key to compare against the value. - A text input to the model. + - `type: "eq" or "ne" or "gt" or 5 more` - - `text: string` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The text 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 - - `type: "input_text"` + - `"eq"` - The type of the input item. Always `input_text`. + - `"ne"` - - `"input_text"` + - `"gt"` - - `prompt_cache_breakpoint: optional object { mode }` + - `"gte"` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `"lt"` - - `mode: "explicit"` + - `"lte"` - The breakpoint mode. Always `explicit`. + - `"in"` - - `"explicit"` + - `"nin"` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `value: string or number or boolean or array of string or number` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The value to compare against the attribute key; supports string, number, or boolean types. - - `detail: "low" or "high" or "auto" or "original"` + - `string` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `number` - - `"low"` + - `boolean` - - `"high"` + - `array of string or number` - - `"auto"` + - `string` - - `"original"` + - `number` - - `type: "input_image"` + - `CompoundFilter object { filters, type }` - The type of the input item. Always `input_image`. + Combine multiple filters using `and` or `or`. - - `"input_image"` + - `filters: array of object { key, type, value } or unknown` - - `file_id: optional string` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - The ID of the file to be sent to the model. + - `ComparisonFilter object { key, type, value }` - - `image_url: optional string` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `key: string` - - `prompt_cache_breakpoint: optional object { mode }` + The key to compare against the value. - Marks the exact end of a reusable 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: "eq" or "ne" or "gt" or 5 more` - - `mode: "explicit"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The breakpoint mode. Always `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 - - `"explicit"` + - `"eq"` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `"ne"` - A file input to the model. + - `"gt"` - - `type: "input_file"` + - `"gte"` - The type of the input item. Always `input_file`. + - `"lt"` - - `"input_file"` + - `"lte"` - - `detail: optional "auto" or "low" or "high"` + - `"in"` - 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`. + - `"nin"` - - `"auto"` + - `value: string or number or boolean or array of string or number` - - `"low"` + The value to compare against the attribute key; supports string, number, or boolean types. - - `"high"` + - `string` - - `file_data: optional string` + - `number` - The content of the file to be sent to the model. + - `boolean` - - `file_id: optional string` + - `array of string or number` - The ID of the file to be sent to the model. + - `string` - - `file_url: optional string` + - `number` - The URL of the file to be sent to the model. + - `unknown` - - `filename: optional string` + - `type: "and" or "or"` - The name of the file to be sent to the model. + Type of operation: `and` or `or`. - - `prompt_cache_breakpoint: optional object { mode }` + - `"and"` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `"or"` - - `mode: "explicit"` + - `max_num_results: optional number` - The breakpoint mode. Always `explicit`. + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `"explicit"` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `status: "in_progress" or "completed" or "incomplete"` + Ranking options for search. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `hybrid_search: optional object { embedding_weight, text_weight }` - - `"in_progress"` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `"completed"` + - `embedding_weight: number` - - `"incomplete"` + The weight of the embedding in the reciprocal ranking fusion. - - `type: "function_call_output"` + - `text_weight: number` - The type of the function tool call output. Always `function_call_output`. + The weight of the text in the reciprocal ranking fusion. - - `"function_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` - - `caller: optional object { type } or 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. - The execution context that produced this tool call. + - `Computer object { type }` - - `Direct 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: "direct"` + - `type: "computer"` - The caller type. Always `direct`. + The type of the computer tool. Always `computer`. - - `"direct"` + - `"computer"` - - `Program object { caller_id, type }` + - `ComputerUsePreview object { display_height, display_width, environment, type }` - - `caller_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 call ID of the program item that produced this tool call. + - `display_height: number` - - `type: "program"` + The height of the computer display. - The caller type. Always `program`. + - `display_width: number` - - `"program"` + The width of the computer display. - - `created_by: optional string` + - `environment: "windows" or "mac" or "linux" or 2 more` - The identifier of the actor that created the item. + The type of computer environment to control. - - `AgentMessage object { id, author, content, 3 more }` + - `"windows"` - - `id: string` + - `"mac"` - The unique ID of the agent message. + - `"linux"` - - `author: string` + - `"ubuntu"` - The sending agent identity. + - `"browser"` - - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` + - `type: "computer_use_preview"` - Encrypted content sent between agents. + The type of the computer use tool. Always `computer_use_preview`. - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `"computer_use_preview"` - A text input to the model. + - `WebSearch object { type, filters, search_context_size, user_location }` - - `BetaResponseOutputText object { annotations, text, type, logprobs }` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - A text output from the model. + - `type: "web_search" or "web_search_2025_08_26"` - - `Text object { text, type }` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - A text content. + - `"web_search"` - - `text: string` + - `"web_search_2025_08_26"` - - `type: "text"` + - `filters: optional object { allowed_domains }` - - `"text"` + Filters for the search. - - `SummaryText object { text, type }` + - `allowed_domains: optional array of string` - A summary text from the model. + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `text: string` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - A summary of the reasoning output from the model so far. + - `search_context_size: optional "low" or "medium" or "high"` - - `type: "summary_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. - The type of the object. Always `summary_text`. + - `"low"` - - `"summary_text"` + - `"medium"` - - `ReasoningText object { text, type }` + - `"high"` - Reasoning text from the model. + - `user_location: optional object { city, country, region, 2 more }` - - `text: string` + The approximate location of the user. - The reasoning text from the model. + - `city: optional string` - - `type: "reasoning_text"` + Free text input for the city of the user, e.g. `San Francisco`. - The type of the reasoning text. Always `reasoning_text`. + - `country: optional string` - - `"reasoning_text"` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `BetaResponseOutputRefusal object { refusal, type }` + - `region: optional string` - A refusal from the model. + Free text input for the region of the user, e.g. `California`. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `timezone: optional string` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` + - `type: optional "approximate"` - A screenshot of a computer. + The type of location approximation. Always `approximate`. - - `detail: "low" or "high" or "auto" or "original"` + - `"approximate"` - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `"low"` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - - `"high"` + - `server_label: string` - - `"auto"` + A label for this MCP server, used to identify it in tool calls. - - `"original"` + - `type: "mcp"` - - `file_id: string` + The type of the MCP tool. Always `mcp`. - The identifier of an uploaded file that contains the screenshot. + - `"mcp"` - - `image_url: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The URL of the screenshot image. + 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"` + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `prompt_cache_breakpoint: optional object { mode }` + List of allowed tool names or a filter 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. + - `McpAllowedTools = array of string` - - `mode: "explicit"` + A string array of allowed tool names - The breakpoint mode. Always `explicit`. + - `McpToolFilter object { read_only, tool_names }` - - `"explicit"` + A filter object to specify which tools are allowed. - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `read_only: optional boolean` - A file input to the model. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `EncryptedContent object { encrypted_content, type }` + - `tool_names: optional array of string` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + List of allowed tool names. - - `encrypted_content: string` + - `authorization: optional string` - Opaque encrypted content. + 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: "encrypted_content"` + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - The type of the input item. Always `encrypted_content`. + 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). - - `"encrypted_content"` + Currently supported `connector_id` values are: - - `recipient: string` + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - The destination agent identity. + - `"connector_dropbox"` - - `type: "agent_message"` + - `"connector_gmail"` - The type of the item. Always `agent_message`. + - `"connector_googlecalendar"` - - `"agent_message"` + - `"connector_googledrive"` - - `agent: optional object { agent_name }` + - `"connector_microsoftteams"` - The agent that produced this item. + - `"connector_outlookcalendar"` - - `agent_name: string` + - `"connector_outlookemail"` - The canonical name of the agent that produced this item. + - `"connector_sharepoint"` - - `MultiAgentCall object { id, action, arguments, 3 more }` + - `defer_loading: optional boolean` - - `id: string` + Whether this MCP tool is deferred and discovered via tool search. - The unique ID of the multi-agent call item. + - `headers: optional map[string]` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - The multi-agent action to execute. + - `require_approval: optional object { always, never } or "always" or "never"` - - `"spawn_agent"` + Specify which of the MCP server's tools require approval. - - `"interrupt_agent"` + - `McpToolApprovalFilter object { always, never }` - - `"list_agents"` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `"send_message"` + - `always: optional object { read_only, tool_names }` - - `"followup_task"` + A filter object to specify which tools are allowed. - - `"wait_agent"` + - `read_only: optional boolean` - - `arguments: 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 JSON string of arguments generated for the action. + - `tool_names: optional array of string` - - `call_id: string` + List of allowed tool names. - The unique ID linking this call to its output. + - `never: optional object { read_only, tool_names }` - - `type: "multi_agent_call"` + A filter object to specify which tools are allowed. - The type of the multi-agent call. Always `multi_agent_call`. + - `read_only: optional boolean` - - `"multi_agent_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. - - `MultiAgentCallOutput object { id, action, call_id, 3 more }` + - `"always"` - - `id: string` + - `"never"` - The unique ID of the multi-agent call output item. + - `server_description: optional string` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + Optional description of the MCP server, used to provide more context. - The multi-agent action that produced this result. + - `server_url: optional string` - - `"spawn_agent"` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `"interrupt_agent"` + - `tunnel_id: optional string` - - `"list_agents"` + 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. - - `"send_message"` + - `CodeInterpreter object { container, type, allowed_callers }` - - `"followup_task"` + A tool that runs Python code to help generate a response to a prompt. - - `"wait_agent"` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `call_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 multi-agent call. + - `string` - - `output: array of BetaResponseOutputText` + The container ID. - Text output returned by the multi-agent action. + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - - `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 }` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - The annotations of the text output. + - `type: "auto"` - - `text: string` + Always `auto`. - The text output from the model. + - `"auto"` - - `type: "output_text"` + - `file_ids: optional array of string` - The type of the output text. Always `output_text`. + An optional list of uploaded files to make available to your code. - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `type: "multi_agent_call_output"` + The memory limit for the code interpreter container. - The type of the multi-agent result. Always `multi_agent_call_output`. + - `"1g"` - - `"multi_agent_call_output"` + - `"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. - - `WebSearchCall object { id, action, status, 2 more }` + - `BetaContainerNetworkPolicyDisabled object { type }` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `type: "disabled"` - - `id: string` + Disable outbound network access. Always `disabled`. - The unique ID of the web search tool call. + - `"disabled"` - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - 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_domains: array of string` - - `Search object { type, queries, query, sources }` + A list of allowed domains when type is `allowlist`. - Action type "search" - Performs a web search query. + - `type: "allowlist"` - - `type: "search"` + Allow outbound network access only to specified domains. Always `allowlist`. - The action type. + - `"allowlist"` - - `"search"` + - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` - - `queries: optional array of string` + Optional domain-scoped secrets for allowlisted domains. - The search queries. + - `domain: string` - - `query: optional string` + The domain associated with the secret. - The search query. + - `name: string` - - `sources: optional array of object { type, url }` + The name of the secret to inject for the domain. - The sources used in the search. + - `value: string` - - `type: "url"` + The secret value to inject for the domain. - The type of source. Always `url`. + - `type: "code_interpreter"` - - `"url"` + The type of the code interpreter tool. Always `code_interpreter`. - - `url: string` + - `"code_interpreter"` - 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. + - `ProgrammaticToolCalling object { type }` - - `"open_page"` + - `type: "programmatic_tool_calling"` - - `url: optional string` + The type of the tool. Always `programmatic_tool_calling`. - The URL opened by the model. + - `"programmatic_tool_calling"` - - `FindInPage object { pattern, type, url }` + - `ImageGeneration object { type, action, background, 9 more }` - Action type "find_in_page": Searches for a pattern within a loaded page. + A tool that generates images using the GPT image models. - - `pattern: string` + - `type: "image_generation"` - The pattern or text to search for within the page. + The type of the image generation tool. Always `image_generation`. - - `type: "find_in_page"` + - `"image_generation"` - The action type. + - `action: optional "generate" or "edit" or "auto"` - - `"find_in_page"` + Whether to generate a new image or edit an existing image. Default: `auto`. - - `url: string` + - `"generate"` - The URL of the page searched for the pattern. + - `"edit"` - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `"auto"` - The status of the web search tool call. + - `background: optional "transparent" or "opaque" or "auto"` - - `"in_progress"` + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - - `"searching"` + - `"transparent"` - - `"completed"` + - `"opaque"` - - `"failed"` + - `"auto"` - - `type: "web_search_call"` + - `input_fidelity: optional "high" or "low"` - The type of the web search tool call. Always `web_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`. - - `"web_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` - - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` + File ID for the mask image. - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + - `image_url: optional string` - - `id: string` + Base64-encoded mask image. - The unique ID of the computer call. + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `call_id: string` + The image generation model to use. Default: `gpt-image-1`. - An identifier used when responding to the tool call with output. + - `string` - - `pending_safety_checks: array of object { id, code, message }` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - The pending safety checks for the computer call. + The image generation model to use. Default: `gpt-image-1`. - - `id: string` + - `"gpt-image-1"` - The ID of the pending safety check. + - `"gpt-image-1-mini"` - - `code: optional string` + - `"gpt-image-1.5"` - The type of the pending safety check. + - `moderation: optional "auto" or "low"` - - `message: optional string` + Moderation level for the generated image. Default: `auto`. - Details about the pending safety check. + - `"auto"` - - `status: "in_progress" or "completed" or "incomplete"` + - `"low"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `output_compression: optional number` - - `"in_progress"` + Compression level for the output image. Default: 100. - - `"completed"` + - `output_format: optional "png" or "webp" or "jpeg"` - - `"incomplete"` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `type: "computer_call"` + - `"png"` - The type of the computer call. Always `computer_call`. + - `"webp"` - - `"computer_call"` + - `"jpeg"` - - `action: optional BetaComputerAction` + - `partial_images: optional number` - A click action. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `Click object { button, type, x, 2 more }` + - `quality: optional "low" or "medium" or "high" or "auto"` - A click action. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `button: "left" or "right" or "wheel" or 2 more` + - `"low"` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `"medium"` - - `"left"` + - `"high"` - - `"right"` + - `"auto"` - - `"wheel"` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `"back"` + 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`. - - `"forward"` + - `string` - - `type: "click"` + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - Specifies the event type. For a click action, this property is always `click`. + 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`. - - `"click"` + - `"1024x1024"` - - `x: number` + - `"1024x1536"` - The x-coordinate where the click occurred. + - `"1536x1024"` - - `y: number` + - `"auto"` - The y-coordinate where the click occurred. + - `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 clicking. + - `type: "local_shell"` - - `DoubleClick object { keys, type, x, y }` + The type of the local shell tool. Always `local_shell`. - A double click action. + - `"local_shell"` - - `keys: array of string` + - `Shell object { type, allowed_callers, environment }` - The keys being held while double-clicking. + A tool that allows the model to execute shell commands. - - `type: "double_click"` + - `type: "shell"` - Specifies the event type. For a double click action, this property is always set to `double_click`. + The type of the shell tool. Always `shell`. - - `"double_click"` + - `"shell"` - - `x: number` + - `allowed_callers: optional array of "direct" or "programmatic"` - The x-coordinate where the double click occurred. + The tool invocation context(s). - - `y: number` + - `"direct"` - The y-coordinate where the double click occurred. + - `"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 }` - - `path: array of object { x, y }` + - `type: "container_auto"` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + Automatically creates a container for this request - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `"container_auto"` - - `x: number` + - `file_ids: optional array of string` - The x-coordinate. + An optional list of uploaded files to make available to your code. - - `y: number` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - The y-coordinate. + The memory limit for the container. - - `type: "drag"` + - `"1g"` - Specifies the event type. For a drag action, this property is always set to `drag`. + - `"4g"` - - `"drag"` + - `"16g"` - - `keys: optional array of string` + - `"64g"` - The keys being held while dragging the mouse. + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `Keypress object { keys, type }` + Network access policy for the container. - A collection of keypresses the model would like to perform. + - `BetaContainerNetworkPolicyDisabled object { type }` - - `keys: array of string` + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `skills: optional array of BetaSkillReference or BetaInlineSkill` - - `type: "keypress"` + An optional list of skills referenced by id or inline data. - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `BetaSkillReference object { skill_id, type, version }` - - `"keypress"` + - `skill_id: string` - - `Move object { type, x, y, keys }` + The ID of the referenced skill. - A mouse move action. + - `type: "skill_reference"` - - `type: "move"` + References a skill created with the /v1/skills endpoint. - Specifies the event type. For a move action, this property is always set to `move`. + - `"skill_reference"` - - `"move"` + - `version: optional string` - - `x: number` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - The x-coordinate to move to. + - `BetaInlineSkill object { description, name, source, type }` - - `y: number` + - `description: string` - The y-coordinate to move to. + The description of the skill. - - `keys: optional array of string` + - `name: string` - The keys being held while moving the mouse. + The name of the skill. - - `Screenshot object { type }` + - `source: BetaInlineSkillSource` - A screenshot action. + Inline skill payload - - `type: "screenshot"` + - `data: string` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + Base64-encoded skill zip bundle. - - `"screenshot"` + - `media_type: "application/zip"` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + The media type of the inline skill payload. Must be `application/zip`. - A scroll action. + - `"application/zip"` - - `scroll_x: number` + - `type: "base64"` - The horizontal scroll distance. + The type of the inline skill source. Must be `base64`. - - `scroll_y: number` + - `"base64"` - The vertical scroll distance. + - `type: "inline"` - - `type: "scroll"` + Defines an inline skill for this request. - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `"inline"` - - `"scroll"` + - `BetaLocalEnvironment object { type, skills }` - - `x: number` + - `type: "local"` - The x-coordinate where the scroll occurred. + Use a local computer environment. - - `y: number` + - `"local"` - The y-coordinate where the scroll occurred. + - `skills: optional array of BetaLocalSkill` - - `keys: optional array of string` + An optional list of skills. - The keys being held while scrolling. + - `description: string` - - `Type object { text, type }` + The description of the skill. - An action to type in text. + - `name: string` - - `text: string` + The name of the skill. - The text to type. + - `path: string` - - `type: "type"` + The path to the directory containing the skill. - Specifies the event type. For a type action, this property is always set to `type`. + - `BetaContainerReference object { container_id, type }` - - `"type"` + - `container_id: string` - - `Wait object { type }` + The ID of the referenced container. - A wait action. + - `type: "container_reference"` - - `type: "wait"` + References a container created with the /v1/containers endpoint - Specifies the event type. For a wait action, this property is always set to `wait`. + - `"container_reference"` - - `"wait"` + - `Custom object { name, type, allowed_callers, 3 more }` - - `actions: optional BetaComputerActionList` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `name: string` - - `Click object { button, type, x, 2 more }` + The name of the custom tool, used to identify it in tool calls. - A click action. + - `type: "custom"` - - `DoubleClick object { keys, type, x, y }` + The type of the custom tool. Always `custom`. - A double click action. + - `"custom"` - - `Drag object { path, type, keys }` + - `allowed_callers: optional array of "direct" or "programmatic"` - A drag action. + The tool invocation context(s). - - `Keypress object { keys, type }` + - `"direct"` - A collection of keypresses the model would like to perform. + - `"programmatic"` - - `Move object { type, x, y, keys }` + - `defer_loading: optional boolean` - A mouse move action. + Whether this tool should be deferred and discovered via tool search. - - `Screenshot object { type }` + - `description: optional string` - A screenshot action. + Optional description of the custom tool, used to provide more context. - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `format: optional object { type } or object { definition, syntax, type }` - A scroll action. + The input format for the custom tool. Default is unconstrained text. - - `Type object { text, type }` + - `Text object { type }` - An action to type in text. + Unconstrained free-form text. - - `Wait object { type }` + - `type: "text"` - A wait action. + 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` - - `ComputerCallOutput object { id, call_id, output, 5 more }` + The grammar definition. - - `id: string` + - `syntax: "lark" or "regex"` - The unique ID of the computer call tool output. + The syntax of the grammar definition. One of `lark` or `regex`. - - `call_id: string` + - `"lark"` - The ID of the computer tool call that produced the output. + - `"regex"` - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `type: "grammar"` - A computer screenshot image used with the computer use tool. + Grammar format. Always `grammar`. - - `type: "computer_screenshot"` + - `"grammar"` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `Namespace object { description, name, tools, type }` - - `"computer_screenshot"` + Groups function/custom tools under a shared namespace. - - `file_id: optional string` + - `description: string` - The identifier of an uploaded file that contains the screenshot. + A description of the namespace shown to the model. - - `image_url: optional string` + - `name: string` - The URL of the screenshot image. + 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](https://platform.openai.com/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 - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + 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 }` @@ -151423,21 +149941,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. @@ -151445,9 +149953,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"` @@ -151455,9 +149963,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 }` @@ -151720,7 +150236,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-web-search). + [web search tool](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -151780,7 +150296,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -151832,7 +150348,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -151978,40 +150494,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`. @@ -152056,19 +150540,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `background: optional "transparent" or "opaque" or "auto"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. - - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. - - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - `"transparent"` @@ -152082,544 +150555,1144 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"high"` - - `"low"` + - `"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 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 - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `Compaction object { encrypted_content, type, id, 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"` - - `input_image_mask: optional object { file_id, image_url }` + The type of the output. Always `image`. - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `"image"` - - `file_id: optional string` + - `url: string` - File ID for the mask image. + The URL of the image output from the code interpreter. - - `image_url: optional string` + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - Base64-encoded mask image. + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `"in_progress"` - The image generation model to use. Default: `gpt-image-1`. + - `"completed"` - - `string` + - `"incomplete"` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `"interpreting"` - The image generation model to use. Default: `gpt-image-1`. + - `"failed"` - - `"gpt-image-1"` + - `type: "code_interpreter_call"` - - `"gpt-image-1-mini"` + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `"gpt-image-2"` + - `"code_interpreter_call"` - - `"gpt-image-2-2026-04-21"` + - `agent: optional object { agent_name }` - - `"gpt-image-1.5"` + The agent that produced this item. - - `"chatgpt-image-latest"` + - `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`. + - `LocalShellCall object { id, action, call_id, 3 more }` - - `"auto"` + A tool call to run a command on the local shell. - - `"low"` + - `id: string` - - `output_compression: optional number` + The unique ID of the local shell call. - Compression level for the output image. Default: 100. + - `action: object { command, env, type, 3 more }` - - `output_format: optional "png" or "webp" or "jpeg"` + Execute a shell command on the server. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `command: array of string` - - `"png"` + The command to run. - - `"webp"` + - `env: map[string]` - - `"jpeg"` + Environment variables to set for the command. - - `partial_images: optional number` + - `type: "exec"` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + The type of the local shell action. Always `exec`. - - `quality: optional "low" or "medium" or "high" or "auto"` + - `"exec"` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `timeout_ms: optional number` - - `"low"` + Optional timeout in milliseconds for the command. - - `"medium"` + - `user: optional string` - - `"high"` + Optional user to run the command as. - - `"auto"` + - `working_directory: optional string` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + Optional working directory to run the command in. - 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` + The unique ID of the local shell tool call generated by the model. - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `status: "in_progress" or "completed" or "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`. + The status of the local shell call. - - `"1024x1024"` + - `"in_progress"` - - `"1024x1536"` + - `"completed"` - - `"1536x1024"` + - `"incomplete"` - - `"auto"` + - `type: "local_shell_call"` - - `LocalShell object { type }` + The type of the local shell call. Always `local_shell_call`. - A tool that allows the model to execute shell commands in a local environment. + - `"local_shell_call"` - - `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. + - `LocalShellCallOutput object { id, output, type, 2 more }` - - `type: "shell"` + The output of a local shell tool call. - The type of the shell tool. Always `shell`. + - `id: string` - - `"shell"` + The unique ID of the local shell tool call generated by the model. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `output: string` - The tool invocation context(s). + A JSON string of the output of the local shell tool call. - - `"direct"` + - `type: "local_shell_call_output"` - - `"programmatic"` + The type of the local shell tool call output. Always `local_shell_call_output`. - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + - `"local_shell_call_output"` - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `agent: optional object { agent_name }` - - `type: "container_auto"` + The agent that produced this item. - Automatically creates a container for this request + - `agent_name: string` - - `"container_auto"` + The canonical name of the agent that produced this item. - - `file_ids: optional array of string` + - `status: optional "in_progress" or "completed" or "incomplete"` - An optional list of uploaded files to make available to your code. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `"in_progress"` - The memory limit for the container. + - `"completed"` - - `"1g"` + - `"incomplete"` - - `"4g"` + - `ShellCall object { action, call_id, type, 5 more }` - - `"16g"` + A tool representing a request to execute one or more shell commands. - - `"64g"` + - `action: object { commands, max_output_length, timeout_ms }` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + The shell commands and limits that describe how to run the tool call. - Network access policy for the container. + - `commands: array of string` - - `BetaContainerNetworkPolicyDisabled object { type }` + Ordered shell commands for the execution environment to run. - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `max_output_length: optional number` - - `skills: optional array of BetaSkillReference or BetaInlineSkill` + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - An optional list of skills referenced by id or inline data. + - `timeout_ms: optional number` - - `BetaSkillReference object { skill_id, type, version }` + Maximum wall-clock time in milliseconds to allow the shell commands to run. - - `skill_id: string` + - `call_id: string` - The ID of the referenced skill. + The unique ID of the shell tool call generated by the model. - - `type: "skill_reference"` + - `type: "shell_call"` - References a skill created with the /v1/skills endpoint. + The type of the item. Always `shell_call`. - - `"skill_reference"` + - `"shell_call"` - - `version: optional string` + - `id: optional string` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + The unique ID of the shell tool call. Populated when this item is returned via API. - - `BetaInlineSkill object { description, name, source, type }` + - `agent: optional object { agent_name }` - - `description: string` + The agent that produced this item. - The description of the skill. + - `agent_name: string` - - `name: string` + The canonical name of the agent that produced this item. - The name of the skill. + - `caller: optional object { type } or object { caller_id, type }` - - `source: BetaInlineSkillSource` + The execution context that produced this tool call. - Inline skill payload + - `Direct object { type }` - - `data: string` + - `type: "direct"` - Base64-encoded skill zip bundle. + The caller type. Always `direct`. - - `media_type: "application/zip"` + - `"direct"` - The media type of the inline skill payload. Must be `application/zip`. + - `Program object { caller_id, type }` - - `"application/zip"` + - `caller_id: string` - - `type: "base64"` + The call ID of the program item that produced this tool call. - The type of the inline skill source. Must be `base64`. + - `type: "program"` - - `"base64"` + The caller type. Always `program`. - - `type: "inline"` + - `"program"` - Defines an inline skill for this request. + - `environment: optional BetaLocalEnvironment or BetaContainerReference` - - `"inline"` + The environment to execute the shell commands in. - `BetaLocalEnvironment object { type, skills }` - - `type: "local"` + - `BetaContainerReference object { container_id, type }` - Use a local computer environment. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"local"` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `skills: optional array of BetaLocalSkill` + - `"in_progress"` - An optional list of skills. + - `"completed"` - - `description: string` + - `"incomplete"` - The description of the skill. + - `ShellCallOutput object { call_id, output, type, 5 more }` - - `name: string` + The streamed output items emitted by a shell tool call. - The name of the skill. + - `call_id: string` - - `path: string` + The unique ID of the shell tool call generated by the model. - The path to the directory containing the skill. + - `output: array of BetaResponseFunctionShellCallOutputContent` - - `BetaContainerReference object { container_id, type }` + Captured chunks of stdout and stderr output, along with their associated outcomes. - - `container_id: string` + - `outcome: object { type } or object { exit_code, type }` - The ID of the referenced container. + The exit or timeout outcome associated with this shell call. - - `type: "container_reference"` + - `Timeout object { type }` - References a container created with the /v1/containers endpoint + Indicates that the shell call exceeded its configured time limit. - - `"container_reference"` + - `type: "timeout"` - - `Custom object { name, type, allowed_callers, 3 more }` + The outcome type. Always `timeout`. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `"timeout"` - - `name: string` + - `Exit object { exit_code, type }` - The name of the custom tool, used to identify it in tool calls. + Indicates that the shell commands finished and returned an exit code. - - `type: "custom"` + - `exit_code: number` - The type of the custom tool. Always `custom`. + The exit code returned by the shell process. - - `"custom"` + - `type: "exit"` - - `allowed_callers: optional array of "direct" or "programmatic"` + The outcome type. Always `exit`. - The tool invocation context(s). + - `"exit"` - - `"direct"` + - `stderr: string` - - `"programmatic"` + Captured stderr output for the shell call. - - `defer_loading: optional boolean` + - `stdout: string` - Whether this tool should be deferred and discovered via tool search. + Captured stdout output for the shell call. - - `description: optional string` + - `type: "shell_call_output"` - Optional description of the custom tool, used to provide more context. + The type of the item. Always `shell_call_output`. - - `format: optional object { type } or object { definition, syntax, type }` + - `"shell_call_output"` - The input format for the custom tool. Default is unconstrained text. + - `id: optional string` - - `Text object { type }` + The unique ID of the shell tool call output. Populated when this item is returned via API. - 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 }` + - `caller: optional object { type } or object { caller_id, type }` - A grammar defined by the user. + The execution context that produced this tool call. - - `definition: string` + - `Direct object { type }` - The grammar definition. + - `type: "direct"` - - `syntax: "lark" or "regex"` + The caller type. Always `direct`. - The syntax of the grammar definition. One of `lark` or `regex`. + - `"direct"` - - `"lark"` + - `Program object { caller_id, type }` - - `"regex"` + - `caller_id: string` - - `type: "grammar"` + The call ID of the program item that produced this tool call. - Grammar format. Always `grammar`. + - `type: "program"` - - `"grammar"` + The caller type. Always `program`. - - `Namespace object { description, name, tools, type }` + - `"program"` - Groups function/custom tools under a shared namespace. + - `max_output_length: optional number` - - `description: string` + The maximum number of UTF-8 characters captured for this shell call's combined output. - A description of the namespace shown to the model. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `name: string` + The status of the shell call output. - The namespace name used in tool calls (for example, `crm`). + - `"in_progress"` - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + - `"completed"` - The function/custom tools available inside this namespace. + - `"incomplete"` - - `Function object { name, type, allowed_callers, 5 more }` + - `ApplyPatchCall object { call_id, operation, status, 4 more }` - - `name: string` + A tool call representing a request to create, delete, or update files using diff patches. - - `type: "function"` + - `call_id: string` - - `"function"` + 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. - - `defer_loading: optional boolean` + - `diff: string` - Whether this function should be deferred and discovered via tool search. + Unified diff content to apply when creating the file. - - `description: optional string` + - `path: string` - - `output_schema: optional map[unknown]` + Path of the file to create relative to the workspace root. - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `type: "create_file"` - - `parameters: optional unknown` + The operation type. Always `create_file`. - - `strict: optional boolean` + - `"create_file"` - Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `DeleteFile object { path, type }` - - `Custom object { name, type, allowed_callers, 3 more }` + Instruction for deleting an existing file via the apply_patch tool. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `path: string` - - `name: string` + Path of the file to delete relative to the workspace root. - The name of the custom tool, used to identify it in tool calls. + - `type: "delete_file"` - - `type: "custom"` + The operation type. Always `delete_file`. - The type of the custom tool. Always `custom`. + - `"delete_file"` - - `"custom"` + - `UpdateFile object { diff, path, type }` - - `allowed_callers: optional array of "direct" or "programmatic"` + Instruction for updating an existing file via the apply_patch tool. - The tool invocation context(s). + - `diff: string` - - `"direct"` + Unified diff content to apply to the existing file. - - `"programmatic"` + - `path: string` - - `defer_loading: optional boolean` + Path of the file to update relative to the workspace root. - Whether this tool should be deferred and discovered via tool search. + - `type: "update_file"` - - `description: optional string` + The operation type. Always `update_file`. - Optional description of the custom tool, used to provide more context. + - `"update_file"` - - `format: optional object { type } or object { definition, syntax, type }` + - `status: "in_progress" or "completed"` - The input format for the custom tool. Default is unconstrained text. + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `Text object { type }` + - `"in_progress"` - Unconstrained free-form text. + - `"completed"` - - `type: "text"` + - `type: "apply_patch_call"` - Unconstrained text format. Always `text`. + The type of the item. Always `apply_patch_call`. - - `"text"` + - `"apply_patch_call"` - - `Grammar object { definition, syntax, type }` + - `id: optional string` - A grammar defined by the user. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `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"` + The caller type. Always `direct`. - - `type: "namespace"` + - `"direct"` - The type of the tool. Always `namespace`. + - `Program object { caller_id, type }` - - `"namespace"` + - `caller_id: string` - - `ToolSearch object { type, description, execution, parameters }` + The call ID of the program item that produced this tool call. - Hosted or BYOT tool search configuration for deferred tools. + - `type: "program"` - - `type: "tool_search"` + The caller type. Always `program`. - The type of the tool. Always `tool_search`. + - `"program"` - - `"tool_search"` + - `ApplyPatchCallOutput object { call_id, status, type, 4 more }` - - `description: optional string` + The streamed output emitted by an apply patch tool call. - 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 apply patch tool call generated by the model. - Whether tool search is executed by the server or by the client. + - `status: "completed" or "failed"` - - `"server"` + The status of the apply patch tool call output. One of `completed` or `failed`. - - `"client"` + - `"completed"` - - `parameters: optional unknown` + - `"failed"` - Parameter schema for a client-executed tool search tool. + - `type: "apply_patch_call_output"` - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + The type of the item. Always `apply_patch_call_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). + - `"apply_patch_call_output"` - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `id: optional string` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `"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"` + - `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 { type, city, country, 2 more }` + - `Program object { caller_id, type }` - The user's location. + - `caller_id: string` - - `type: "approximate"` + The call ID of the program item that produced this tool call. - The type of location approximation. Always `approximate`. + - `type: "program"` - - `"approximate"` + The caller type. Always `program`. - - `city: optional string` + - `"program"` - Free text input for the city of the user, e.g. `San Francisco`. + - `output: optional string` - - `country: optional string` + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - 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: "tool_search_output"` + - `description: optional string` - The type of the item. Always `tool_search_output`. + The description of the tool. - - `"tool_search_output"` + - `type: "mcp_list_tools"` + + The type of the item. Always `mcp_list_tools`. + + - `"mcp_list_tools"` - `agent: optional object { agent_name }` @@ -152629,1051 +151702,1029 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `created_by: optional string` + - `error: optional string` - The identifier of the actor that created the item. + Error message if the server could not list tools. - - `AdditionalTools object { id, role, tools, 2 more }` + - `McpApprovalRequest object { id, arguments, name, 3 more }` + + A request for human approval of a tool invocation. - `id: string` - The unique ID of the additional tools item. + The unique ID of the approval request. - - `role: "unknown" or "user" or "assistant" or 5 more` + - `arguments: string` - The role that provided the additional tools. + A JSON string of arguments for the tool. - - `"unknown"` + - `name: string` - - `"user"` + The name of the tool to run. - - `"assistant"` + - `server_label: string` - - `"system"` + The label of the MCP server making the request. - - `"critic"` + - `type: "mcp_approval_request"` - - `"discriminator"` + The type of the item. Always `mcp_approval_request`. - - `"developer"` + - `"mcp_approval_request"` - - `"tool"` + - `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. - The additional tool definitions 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). + - `McpApprovalResponse object { approval_request_id, approve, type, 3 more }` - - `name: string` + A response to an MCP approval request. - The name of the function to call. + - `approval_request_id: string` - - `parameters: map[unknown]` + The ID of the approval request being answered. - A JSON schema object describing the parameters of the function. + - `approve: boolean` - - `strict: boolean` + Whether the request was approved. - Whether strict parameter validation is enforced for this function tool. + - `type: "mcp_approval_response"` - - `type: "function"` + The type of the item. Always `mcp_approval_response`. - The type of the function tool. Always `function`. + - `"mcp_approval_response"` - - `"function"` + - `id: optional string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The unique ID of the approval response - 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. + - `reason: optional string` - - `description: optional string` + Optional reason for the decision. - A description of the function. Used by the model to determine whether or not to call the function. + - `McpCall object { id, arguments, name, 7 more }` - - `output_schema: optional map[unknown]` + An invocation of a tool on an MCP server. - 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 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). + - `arguments: string` - - `type: "file_search"` + A JSON string of the arguments passed to the tool. - The type of the file search tool. Always `file_search`. + - `name: string` - - `"file_search"` + The name of the tool that was run. - - `vector_store_ids: array of string` + - `server_label: string` - The IDs of the vector stores to search. + The label of the MCP server running the tool. - - `filters: optional object { key, type, value } or object { filters, type }` + - `type: "mcp_call"` - A filter to apply. + The type of the item. Always `mcp_call`. - - `ComparisonFilter object { key, type, value }` + - `"mcp_call"` - 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`. + - `approval_request_id: 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 + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - - `"eq"` + - `error: optional string` - - `"ne"` + The error from the tool call, if any. - - `"gt"` + - `output: optional string` - - `"gte"` + The output from the tool call. - - `"lt"` + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - - `"lte"` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `"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. + - `"calling"` - - `string` + - `"failed"` - - `number` + - `CustomToolCallOutput object { call_id, output, type, 3 more }` - - `boolean` + The output of a custom tool call from your code, being sent back to the model. - - `array of string or number` + - `call_id: string` - - `string` + The call ID, used to map this custom tool call output to a custom tool call. - - `number` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `CompoundFilter object { filters, type }` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - Combine multiple filters using `and` or `or`. + - `StringOutput = string` - - `filters: array of object { key, type, value } or unknown` + A string of the output of the custom tool call. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `ComparisonFilter object { key, type, value }` + Text, image, or file output of the custom tool call. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `key: string` + A text input to the model. - The key to compare against the value. + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `type: "eq" or "ne" or "gt" or 5 more` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `BetaResponseInputFile 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: "custom_tool_call_output"` - - `"ne"` + The type of the custom tool call output. Always `custom_tool_call_output`. - - `"gt"` + - `"custom_tool_call_output"` - - `"gte"` + - `id: optional string` - - `"lt"` + The unique ID of the custom tool call output in the OpenAI platform. - - `"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. + - `caller: optional object { type } or object { caller_id, type }` - - `string` + The execution context that produced this tool call. - - `number` + - `Direct object { type }` - - `boolean` + - `type: "direct"` - - `array of string or number` + The caller type. Always `direct`. - - `string` + - `"direct"` - - `number` + - `Program object { caller_id, type }` - - `unknown` + - `caller_id: string` - - `type: "and" or "or"` + The call ID of the program item that produced this tool call. - Type of operation: `and` or `or`. + - `type: "program"` - - `"and"` + The caller type. Always `program`. - - `"or"` + - `"program"` - - `max_num_results: optional number` + - `CustomToolCall object { call_id, input, name, 5 more }` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + A call to a custom tool created by the model. - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `call_id: string` - Ranking options for search. + An identifier used to map this custom tool call to a tool call output. - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `input: string` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + The input for the custom tool call generated by the model. - - `embedding_weight: number` + - `name: string` - The weight of the embedding in the reciprocal ranking fusion. + The name of the custom tool being called. - - `text_weight: number` + - `type: "custom_tool_call"` - The weight of the text in the reciprocal ranking fusion. + The type of the custom tool call. Always `custom_tool_call`. - - `ranker: optional "auto" or "default-2024-11-15"` + - `"custom_tool_call"` - The ranker to use for the file search. + - `id: optional string` - - `"auto"` + The unique ID of the custom tool call in the OpenAI platform. - - `"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` + - `namespace: optional string` - The type of computer environment to control. + The namespace of the custom tool being called. - - `"windows"` + - `CompactionTrigger object { type, agent }` - - `"mac"` + Compacts the current context. Must be the final input item. - - `"linux"` + - `type: "compaction_trigger"` - - `"ubuntu"` + The type of the item. Always `compaction_trigger`. - - `"browser"` + - `"compaction_trigger"` - - `type: "computer_use_preview"` + - `agent: optional object { agent_name }` - The type of the computer use tool. Always `computer_use_preview`. + The agent that produced this item. - - `"computer_use_preview"` + - `agent_name: string` - - `WebSearch object { type, filters, search_context_size, user_location }` + The canonical name of the agent that produced this item. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `ItemReference object { id, agent, type }` - - `type: "web_search" or "web_search_2025_08_26"` + An internal identifier for an item to reference. - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `id: string` - - `"web_search"` + The ID of the item to reference. - - `"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. + - `type: optional "item_reference"` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + The type of item to reference. Always `item_reference`. - - `search_context_size: optional "low" or "medium" or "high"` + - `"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. + - `Program object { id, call_id, code, 3 more }` - - `"low"` + - `id: string` - - `"medium"` + The unique ID of this program item. - - `"high"` + - `call_id: string` - - `user_location: optional object { city, country, region, 2 more }` + The stable call ID of the program item. - The approximate location of the user. + - `code: string` - - `city: optional string` + The JavaScript source executed by programmatic tool calling. - Free text input for the city of the user, e.g. `San Francisco`. + - `fingerprint: string` - - `country: optional string` + Opaque program replay fingerprint that must be round-tripped. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `type: "program"` - - `region: optional string` + The item type. Always `program`. - Free text input for the region of the user, e.g. `California`. + - `"program"` - - `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. - - `type: optional "approximate"` + - `agent_name: string` - The type of location approximation. Always `approximate`. + The canonical name of the agent that produced this item. - - `"approximate"` + - `ProgramOutput object { id, call_id, result, 3 more }` - - `Mcp object { server_label, type, allowed_callers, 9 more }` + - `id: string` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + The unique ID of this program output item. - - `server_label: string` + - `call_id: string` - A label for this MCP server, used to identify it in tool calls. + The call ID of the program item. - - `type: "mcp"` + - `result: string` - The type of the MCP tool. Always `mcp`. + The result produced by the program item. - - `"mcp"` + - `status: "completed" or "incomplete"` - - `allowed_callers: optional array of "direct" or "programmatic"` + The terminal status of the program output. - The tool invocation context(s). + - `"completed"` - - `"direct"` + - `"incomplete"` - - `"programmatic"` + - `type: "program_output"` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + The item type. Always `program_output`. - List of allowed tool names or a filter object. + - `"program_output"` - - `McpAllowedTools = array of string` + - `agent: optional object { agent_name }` - A string array of allowed tool names + The agent that produced this item. - - `McpToolFilter 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` + - `metadata: map[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. + 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. - - `tool_names: optional array of string` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - List of allowed tool names. + - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` - - `authorization: optional 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. - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. + - `"gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more` - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" 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. - 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + - `"gpt-5.6-sol"` - Currently supported `connector_id` values are: + - `"gpt-5.6-terra"` - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + - `"gpt-5.6-luna"` - - `"connector_dropbox"` + - `"gpt-5.4"` - - `"connector_gmail"` + - `"gpt-5.4-mini"` - - `"connector_googlecalendar"` + - `"gpt-5.4-nano"` - - `"connector_googledrive"` + - `"gpt-5.4-mini-2026-03-17"` - - `"connector_microsoftteams"` + - `"gpt-5.4-nano-2026-03-17"` - - `"connector_outlookcalendar"` + - `"gpt-5.3-chat-latest"` - - `"connector_outlookemail"` + - `"gpt-5.2"` - - `"connector_sharepoint"` + - `"gpt-5.2-2025-12-11"` - - `defer_loading: optional boolean` + - `"gpt-5.2-chat-latest"` - Whether this MCP tool is deferred and discovered via tool search. + - `"gpt-5.2-pro"` - - `headers: optional map[string]` + - `"gpt-5.2-pro-2025-12-11"` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `"gpt-5.1"` - - `require_approval: optional object { always, never } or "always" or "never"` + - `"gpt-5.1-2025-11-13"` - Specify which of the MCP server's tools require approval. + - `"gpt-5.1-codex"` - - `McpToolApprovalFilter object { always, never }` + - `"gpt-5.1-mini"` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `"gpt-5.1-chat-latest"` - - `always: optional object { read_only, tool_names }` + - `"gpt-5"` - A filter object to specify which tools are allowed. + - `"gpt-5-mini"` - - `read_only: optional boolean` + - `"gpt-5-nano"` - 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-5-2025-08-07"` - - `tool_names: optional array of string` + - `"gpt-5-mini-2025-08-07"` - List of allowed tool names. + - `"gpt-5-nano-2025-08-07"` - - `never: optional object { read_only, tool_names }` + - `"gpt-5-chat-latest"` - A filter object to specify which tools are allowed. + - `"gpt-4.1"` - - `read_only: optional boolean` + - `"gpt-4.1-mini"` - 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-nano"` - - `tool_names: optional array of string` + - `"gpt-4.1-2025-04-14"` - List of allowed tool names. + - `"gpt-4.1-mini-2025-04-14"` + + - `"gpt-4.1-nano-2025-04-14"` - - `McpToolApprovalSetting = "always" or "never"` + - `"o4-mini"` - 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. + - `"o4-mini-2025-04-16"` - - `"always"` + - `"o3"` - - `"never"` + - `"o3-2025-04-16"` - - `server_description: optional string` + - `"o3-mini"` - Optional description of the MCP server, used to provide more context. + - `"o3-mini-2025-01-31"` - - `server_url: optional string` + - `"o1"` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `"o1-2024-12-17"` - - `tunnel_id: optional string` + - `"o1-preview"` - 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. + - `"o1-preview-2024-09-12"` - - `CodeInterpreter object { container, type, allowed_callers }` + - `"o1-mini"` - A tool that runs Python code to help generate a response to a prompt. + - `"o1-mini-2024-09-12"` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + - `"gpt-4o"` - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + - `"gpt-4o-2024-11-20"` - - `string` + - `"gpt-4o-2024-08-06"` - The container ID. + - `"gpt-4o-2024-05-13"` - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + - `"gpt-4o-audio-preview"` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `"gpt-4o-audio-preview-2024-10-01"` - - `type: "auto"` + - `"gpt-4o-audio-preview-2024-12-17"` - Always `auto`. + - `"gpt-4o-audio-preview-2025-06-03"` - - `"auto"` + - `"gpt-4o-mini-audio-preview"` - - `file_ids: optional array of string` + - `"gpt-4o-mini-audio-preview-2024-12-17"` - An optional list of uploaded files to make available to your code. + - `"gpt-4o-search-preview"` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `"gpt-4o-mini-search-preview"` - The memory limit for the code interpreter container. + - `"gpt-4o-search-preview-2025-03-11"` - - `"1g"` + - `"gpt-4o-mini-search-preview-2025-03-11"` - - `"4g"` + - `"chatgpt-4o-latest"` - - `"16g"` + - `"codex-mini-latest"` - - `"64g"` + - `"gpt-4o-mini"` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `"gpt-4o-mini-2024-07-18"` - Network access policy for the container. + - `"gpt-4-turbo"` - - `BetaContainerNetworkPolicyDisabled object { type }` + - `"gpt-4-turbo-2024-04-09"` - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `"gpt-4-0125-preview"` - - `type: "code_interpreter"` + - `"gpt-4-turbo-preview"` - The type of the code interpreter tool. Always `code_interpreter`. + - `"gpt-4-1106-preview"` - - `"code_interpreter"` + - `"gpt-4-vision-preview"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"gpt-4"` - The tool invocation context(s). + - `"gpt-4-0314"` - - `"direct"` + - `"gpt-4-0613"` - - `"programmatic"` + - `"gpt-4-32k"` - - `ProgrammaticToolCalling object { type }` + - `"gpt-4-32k-0314"` - - `type: "programmatic_tool_calling"` + - `"gpt-4-32k-0613"` - The type of the tool. Always `programmatic_tool_calling`. + - `"gpt-3.5-turbo"` - - `"programmatic_tool_calling"` + - `"gpt-3.5-turbo-16k"` - - `ImageGeneration object { type, action, background, 9 more }` + - `"gpt-3.5-turbo-0301"` - A tool that generates images using the GPT image models. + - `"gpt-3.5-turbo-0613"` - - `type: "image_generation"` + - `"gpt-3.5-turbo-1106"` - The type of the image generation tool. Always `image_generation`. + - `"gpt-3.5-turbo-0125"` - - `"image_generation"` + - `"gpt-3.5-turbo-16k-0613"` - - `action: optional "generate" or "edit" or "auto"` + - `"o1-pro"` - Whether to generate a new image or edit an existing image. Default: `auto`. + - `"o1-pro-2025-03-19"` - - `"generate"` + - `"o3-pro"` - - `"edit"` + - `"o3-pro-2025-06-10"` - - `"auto"` + - `"o3-deep-research"` - - `background: optional "transparent" or "opaque" or "auto"` + - `"o3-deep-research-2025-06-26"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + - `"o4-mini-deep-research"` - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + - `"o4-mini-deep-research-2025-06-26"` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `"computer-use-preview"` - - `"transparent"` + - `"computer-use-preview-2025-03-11"` - - `"opaque"` + - `"gpt-5-codex"` - - `"auto"` + - `"gpt-5-pro"` - - `input_fidelity: optional "high" or "low"` + - `"gpt-5-pro-2025-10-06"` - 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-codex-max"` - - `"high"` + - `string` - - `"low"` + - `object: "response"` - - `input_image_mask: optional object { file_id, image_url }` + The object type of this resource - always set to `response`. - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `"response"` - - `file_id: optional string` + - `output: array of BetaResponseOutputItem` - File ID for the mask image. + An array of content items generated by the model. - - `image_url: 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. - Base64-encoded mask image. + - `BetaResponseOutputMessage object { id, content, role, 4 more }` - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + An output message from the model. - 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-2" or 3 more` + - `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-2"` + - `status: "in_progress" or "searching" or "completed" or 2 more` - - `"gpt-image-2-2026-04-21"` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `"gpt-image-1.5"` + - `"in_progress"` - - `"chatgpt-image-latest"` + - `"searching"` - - `moderation: optional "auto" or "low"` + - `"completed"` - Moderation level for the generated image. Default: `auto`. + - `"incomplete"` - - `"auto"` + - `"failed"` - - `"low"` + - `type: "file_search_call"` - - `output_compression: optional number` + The type of the file search tool call. Always `file_search_call`. - Compression level for the output image. Default: 100. + - `"file_search_call"` - - `output_format: optional "png" or "webp" or "jpeg"` + - `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"` + - `results: optional array of object { attributes, file_id, filename, 2 more }` - - `partial_images: optional number` + The results of the file search tool call. - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `attributes: optional map[string or number or boolean]` - - `quality: optional "low" or "medium" or "high" or "auto"` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. Keys are strings + with a maximum length of 64 characters. Values are strings with a maximum + length of 512 characters, booleans, or numbers. - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `string` - - `"low"` + - `number` - - `"medium"` + - `boolean` - - `"high"` + - `file_id: optional string` - - `"auto"` + The unique ID of the file. - - `size: optional string or "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. - - `string` + - `score: optional number` - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + The relevance score of the file - a value between 0 and 1. - 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: optional string` - - `"1024x1024"` + The text that was retrieved from the file. - - `"1024x1536"` + - `FunctionCall object { arguments, call_id, name, 6 more }` - - `"1536x1024"` + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. - - `"auto"` + - `arguments: string` - - `LocalShell object { type }` + A JSON string of the arguments to pass to the function. - A tool that allows the model to execute shell commands in a local environment. + - `call_id: string` - - `type: "local_shell"` + The unique ID of the function tool call generated by the model. - The type of the local shell tool. Always `local_shell`. + - `name: string` - - `"local_shell"` + The name of the function to run. - - `Shell object { type, allowed_callers, environment }` + - `type: "function_call"` - A tool that allows the model to execute shell commands. + The type of the function tool call. Always `function_call`. - - `type: "shell"` + - `"function_call"` - The type of the shell tool. Always `shell`. + - `id: optional string` - - `"shell"` + The unique ID of the function tool 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. - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + - `caller: optional object { type } or object { caller_id, type }` - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + The execution context that produced this tool call. - - `BetaLocalEnvironment object { type, skills }` + - `Direct object { type }` - - `BetaContainerReference object { container_id, type }` + - `type: "direct"` - - `Custom object { name, type, allowed_callers, 3 more }` + - `"direct"` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `Program object { caller_id, type }` - - `name: string` + - `caller_id: string` - The name of the custom tool, used to identify it in tool calls. + The call ID of the program item that produced this tool call. - - `type: "custom"` + - `type: "program"` - The type of the custom tool. Always `custom`. + - `"program"` - - `"custom"` + - `namespace: optional string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The namespace of the function to run. - 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 tool should be deferred and discovered via tool search. + - `"incomplete"` - - `description: optional string` + - `FunctionCallOutput 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 function call tool output. - The input format for the custom tool. Default is unconstrained text. + - `call_id: string` - - `Text object { type }` + The unique ID of the function tool call generated by the model. - Unconstrained free-form text. + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `type: "text"` + The output from the function call generated by your code. + Can be a string or an list of output content. - Unconstrained text format. Always `text`. + - `StringOutput = string` - - `"text"` + A string of the output of the function call. - - `Grammar object { definition, syntax, type }` + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - A grammar defined by the user. + Text, image, or file output of the function call. - - `definition: string` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - The grammar definition. + A text input to the model. - - `syntax: "lark" or "regex"` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - The syntax of the grammar definition. One of `lark` or `regex`. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `"lark"` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `"regex"` + A file input to the model. - - `type: "grammar"` + - `status: "in_progress" or "completed" or "incomplete"` - Grammar format. Always `grammar`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"grammar"` + - `"in_progress"` - - `Namespace object { description, name, tools, type }` + - `"completed"` - Groups function/custom tools under a shared namespace. + - `"incomplete"` - - `description: string` + - `type: "function_call_output"` - A description of the namespace shown to the model. + The type of the function tool call output. Always `function_call_output`. - - `name: string` + - `"function_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` + - `caller: optional object { type } or object { caller_id, type }` - - `type: "function"` + The execution context that produced this tool call. - - `"function"` + - `Direct object { type }` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `type: "direct"` - The tool invocation context(s). + The caller type. Always `direct`. - `"direct"` - - `"programmatic"` + - `Program object { caller_id, type }` - - `defer_loading: optional boolean` + - `caller_id: string` - Whether this function 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"` - - `output_schema: optional map[unknown]` + The caller type. Always `program`. - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `"program"` - - `parameters: optional unknown` + - `created_by: optional string` - - `strict: optional boolean` + The identifier of the actor that created the 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. + - `AgentMessage object { id, author, content, 3 more }` - - `Custom object { name, type, allowed_callers, 3 more }` + - `id: string` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The unique ID of the agent message. - - `name: string` + - `author: string` - The name of the custom tool, used to identify it in tool calls. + The sending agent identity. - - `type: "custom"` + - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` - The type of the custom tool. Always `custom`. + Encrypted content sent between agents. - - `"custom"` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `allowed_callers: optional array of "direct" or "programmatic"` + A text input to the model. - The tool invocation context(s). + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - - `"direct"` + A text output from the model. - - `"programmatic"` + - `Text object { text, type }` - - `defer_loading: optional boolean` + A text content. - Whether this tool should be deferred and discovered via tool search. + - `text: string` - - `description: optional string` + - `type: "text"` - Optional description of the custom tool, used to provide more context. + - `"text"` - - `format: optional object { type } or object { definition, syntax, type }` + - `SummaryText object { text, type }` - The input format for the custom tool. Default is unconstrained text. + A summary text from the model. - - `Text object { type }` + - `text: string` - Unconstrained free-form text. + A summary of the reasoning output from the model so far. - - `type: "text"` + - `type: "summary_text"` - Unconstrained text format. Always `text`. + The type of the object. Always `summary_text`. - - `"text"` + - `"summary_text"` - - `Grammar object { definition, syntax, type }` + - `ReasoningText object { text, type }` - A grammar defined by the user. + Reasoning text from the model. - - `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"` + - `BetaResponseOutputRefusal object { refusal, type }` - - `type: "grammar"` + A refusal from 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"` + - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` - The type of the tool. Always `namespace`. + A screenshot of a computer. - - `"namespace"` + - `detail: "low" or "high" or "auto" or "original"` - - `ToolSearch object { type, description, execution, parameters }` + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - Hosted or BYOT tool search configuration for deferred tools. + - `"low"` - - `type: "tool_search"` + - `"high"` - The type of the tool. Always `tool_search`. + - `"auto"` - - `"tool_search"` + - `"original"` - - `description: optional string` + - `file_id: string` - Description shown to the model for a client-executed tool search tool. + The identifier of an uploaded file that contains the screenshot. - - `execution: optional "server" or "client"` + - `image_url: string` - Whether tool search is executed by the server or by the client. + The URL of the screenshot image. - - `"server"` + - `type: "computer_screenshot"` - - `"client"` + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `parameters: optional unknown` + - `"computer_screenshot"` - Parameter schema for a client-executed tool search tool. + - `prompt_cache_breakpoint: optional object { mode }` - - `WebSearchPreview object { type, search_content_types, 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. - 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). + - `mode: "explicit"` - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + The breakpoint mode. Always `explicit`. - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `"explicit"` - - `"web_search_preview"` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `"web_search_preview_2025_03_11"` + A file input to the model. - - `search_content_types: optional array of "text" or "image"` + - `EncryptedContent object { encrypted_content, type }` - - `"text"` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `"image"` + - `encrypted_content: string` - - `search_context_size: optional "low" or "medium" or "high"` + Opaque encrypted 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: "encrypted_content"` - - `"low"` + The type of the input item. Always `encrypted_content`. - - `"medium"` + - `"encrypted_content"` - - `"high"` + - `recipient: string` - - `user_location: optional object { type, city, country, 2 more }` + The destination agent identity. - The user's location. + - `type: "agent_message"` - - `type: "approximate"` + The type of the item. Always `agent_message`. - The type of location approximation. Always `approximate`. + - `"agent_message"` - - `"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`. + - `MultiAgentCall object { id, action, arguments, 3 more }` - - `region: optional string` + - `id: string` - Free text input for the region of the user, e.g. `California`. + The unique ID of the multi-agent call item. - - `timezone: optional string` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The multi-agent action to execute. - - `ApplyPatch object { type, allowed_callers }` + - `"spawn_agent"` - Allows the assistant to create, delete, or update files using unified diffs. + - `"interrupt_agent"` - - `type: "apply_patch"` + - `"list_agents"` - The type of the tool. Always `apply_patch`. + - `"send_message"` - - `"apply_patch"` + - `"followup_task"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"wait_agent"` - The tool invocation context(s). + - `arguments: string` - - `"direct"` + The JSON string of arguments generated for the action. - - `"programmatic"` + - `call_id: string` - - `type: "additional_tools"` + The unique ID linking this call to its output. - The type of the item. Always `additional_tools`. + - `type: "multi_agent_call"` - - `"additional_tools"` + The type of the multi-agent call. Always `multi_agent_call`. + + - `"multi_agent_call"` - `agent: optional object { agent_name }` @@ -153683,65 +152734,55 @@ 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](https://platform.openai.com/docs/api-reference/responses/compact). + - `MultiAgentCallOutput object { id, action, call_id, 3 more }` - `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`. + The unique ID of the multi-agent call output item. - - `"compaction"` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `agent: optional object { agent_name }` + The multi-agent action that produced this result. - The agent that produced this item. + - `"spawn_agent"` - - `agent_name: string` + - `"interrupt_agent"` - The canonical name of the agent that produced this item. + - `"list_agents"` - - `created_by: optional string` + - `"send_message"` - The identifier of the actor that created the item. + - `"followup_task"` - - `ImageGenerationCall object { id, result, status, 2 more }` + - `"wait_agent"` - An image generation request made by the model. + - `call_id: string` - - `id: string` + The unique ID of the multi-agent call. - The unique ID of the image generation call. + - `output: array of BetaResponseOutputText` - - `result: string` + Text output returned by the multi-agent action. - The generated image encoded in base64. + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` - - `status: "in_progress" or "completed" or "generating" or "failed"` + The annotations of the text output. - The status of the image generation call. + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - - `"in_progress"` + - `text: string` - - `"completed"` + The text output from the model. - - `"generating"` + - `type: "output_text"` - - `"failed"` + The type of the output text. Always `output_text`. - - `type: "image_generation_call"` + - `type: "multi_agent_call_output"` - The type of the image generation call. Always `image_generation_call`. + The type of the multi-agent result. Always `multi_agent_call_output`. - - `"image_generation_call"` + - `"multi_agent_call_output"` - `agent: optional object { agent_name }` @@ -153751,166 +152792,164 @@ 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 }` + - `WebSearchCall object { id, action, status, 2 more }` - A tool call to run code. + 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 code interpreter tool call. - - - `code: string` - - The code to run, or null if not available. + The unique ID of the web search tool call. - - `container_id: string` + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - The ID of the container used to run the 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). - - `outputs: array of object { logs, type } or object { type, url }` + - `Search object { type, queries, query, sources }` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + Action type "search" - Performs a web search query. - - `Logs object { logs, type }` + - `type: "search"` - The logs output from the code interpreter. + The action type. - - `logs: string` + - `"search"` - The logs output from the code interpreter. + - `queries: optional array of string` - - `type: "logs"` + The search queries. - The type of the output. Always `logs`. + - `query: optional string` - - `"logs"` + The search query. - - `Image object { type, url }` + - `sources: optional array of object { type, url }` - The image output from the code interpreter. + The sources used in the search. - - `type: "image"` + - `type: "url"` - The type of the output. Always `image`. + The type of source. Always `url`. - - `"image"` + - `"url"` - `url: string` - The URL of the image output from the code interpreter. + The URL of the source. - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + - `OpenPage object { type, url }` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + Action type "open_page" - Opens a specific URL from search results. - - `"in_progress"` + - `type: "open_page"` - - `"completed"` + The action type. - - `"incomplete"` + - `"open_page"` - - `"interpreting"` + - `url: optional string` - - `"failed"` + The URL opened by the model. - - `type: "code_interpreter_call"` + - `FindInPage object { pattern, type, url }` - The type of the code interpreter tool call. Always `code_interpreter_call`. + Action type "find_in_page": Searches for a pattern within a loaded page. - - `"code_interpreter_call"` + - `pattern: string` - - `agent: optional object { agent_name }` + The pattern or text to search for within the page. - The agent that produced this item. + - `type: "find_in_page"` - - `agent_name: string` + The action type. - The canonical name of the agent that produced this item. + - `"find_in_page"` - - `LocalShellCall object { id, action, call_id, 3 more }` + - `url: string` - A tool call to run a command on the local shell. + The URL of the page searched for the pattern. - - `id: string` + - `status: "in_progress" or "searching" or "completed" or "failed"` - The unique ID of the local shell call. + The status of the web search tool call. - - `action: object { command, env, type, 3 more }` + - `"in_progress"` - Execute a shell command on the server. + - `"searching"` - - `command: array of string` + - `"completed"` - The command to run. + - `"failed"` - - `env: map[string]` + - `type: "web_search_call"` - Environment variables to set for the command. + The type of the web search tool call. Always `web_search_call`. - - `type: "exec"` + - `"web_search_call"` - The type of the local shell action. Always `exec`. + - `agent: optional object { agent_name }` - - `"exec"` + The agent that produced this item. - - `timeout_ms: optional number` + - `agent_name: string` - Optional timeout in milliseconds for the command. + The canonical name of the agent that produced this item. - - `user: optional string` + - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` - Optional user to run the command as. + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - - `working_directory: optional string` + - `id: string` - Optional working directory to run the command in. + The unique ID of the computer call. - `call_id: string` - The unique ID of the local shell tool call generated by the model. - - - `status: "in_progress" or "completed" or "incomplete"` + An identifier used when responding to the tool call with output. - The status of the local shell call. + - `pending_safety_checks: array of object { id, code, message }` - - `"in_progress"` + The pending safety checks for the computer call. - - `"completed"` + - `id: string` - - `"incomplete"` + The ID of the pending safety check. - - `type: "local_shell_call"` + - `code: optional string` - The type of the local shell call. Always `local_shell_call`. + The type of the pending safety check. - - `"local_shell_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"` - - `LocalShellCallOutput object { id, output, type, 2 more }` + - `"completed"` - The output of a local shell tool call. + - `"incomplete"` - - `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 }` @@ -153920,83 +152959,98 @@ 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"` + - `ComputerCallOutput object { id, call_id, output, 5 more }` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `id: string` - - `"in_progress"` + 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"` - - `ShellCall object { id, action, call_id, 6 more }` - - A tool call that executes one or more shell commands in a managed environment. + - `"failed"` - - `id: string` + - `"in_progress"` - The unique ID of the shell tool call. Populated when this item is returned via API. + - `type: "computer_call_output"` - - `action: object { commands, max_output_length, timeout_ms }` + The type of the computer tool call output. Always `computer_call_output`. - The shell commands and limits that describe how to run the tool call. + - `"computer_call_output"` - - `commands: array of string` + - `acknowledged_safety_checks: optional array of object { id, code, message }` - - `max_output_length: number` + The safety checks reported by the API that have been acknowledged by the + developer. - Optional maximum number of characters to return from each command. + - `id: string` - - `timeout_ms: number` + The ID of the pending safety check. - Optional timeout in milliseconds for the commands. + - `code: optional string` - - `call_id: string` + The type of the pending safety check. - The unique ID of the shell tool call generated by the model. + - `message: optional string` - - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` + Details about the pending safety check. - Represents the use of a local environment to perform shell actions. + - `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`. + - `created_by: optional string` - - `"local"` + The identifier of the actor that created the item. - - `BetaResponseContainerReference object { container_id, type }` + - `Reasoning object { id, summary, type, 4 more }` - Represents a container created with /v1/containers. + 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). - - `container_id: string` + - `id: string` - - `type: "container_reference"` + The unique identifier of the reasoning content. - The environment type. Always `container_reference`. + - `summary: array of object { text, type }` - - `"container_reference"` + Reasoning summary content. - - `status: "in_progress" or "completed" or "incomplete"` + - `text: string` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + 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"` - - `type: "shell_call"` + - `type: "reasoning"` - The type of the item. Always `shell_call`. + The type of the object. Always `reasoning`. - - `"shell_call"` + - `"reasoning"` - `agent: optional object { agent_name }` @@ -154006,1139 +153060,1180 @@ 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 }` + - `content: optional array of object { text, type }` - The execution context that produced this tool call. + Reasoning text content. - - `Direct object { type }` + - `text: string` - - `type: "direct"` + The reasoning text from the model. - - `"direct"` + - `type: "reasoning_text"` - - `Program object { caller_id, type }` + The type of the reasoning text. Always `reasoning_text`. - - `caller_id: string` + - `"reasoning_text"` - The call ID of the program item that produced this tool call. + - `encrypted_content: optional string` - - `type: "program"` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - - `"program"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `created_by: optional string` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The ID of the entity that created this tool call. + - `"in_progress"` - - `ShellCallOutput object { id, call_id, max_output_length, 6 more }` + - `"completed"` - The output of a shell tool call that was emitted. + - `"incomplete"` + + - `Program object { id, call_id, code, 3 more }` - `id: string` - The unique ID of the shell call output. Populated when this item is returned via API. + The unique ID of the program item. - `call_id: string` - The unique ID of the shell tool call generated by the model. + The stable call ID of the program item. - - `max_output_length: number` + - `code: 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 JavaScript source executed by programmatic tool calling. - - `output: array of object { outcome, stderr, stdout, created_by }` + - `fingerprint: string` - An array of shell call output contents + Opaque program replay fingerprint that must be round-tripped. - - `outcome: object { type } or object { exit_code, type }` + - `type: "program"` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + The type of the item. Always `program`. - - `Timeout object { type }` + - `"program"` - Indicates that the shell call exceeded its configured time limit. + - `agent: optional object { agent_name }` - - `type: "timeout"` + The agent that produced this item. - The outcome type. Always `timeout`. + - `agent_name: string` - - `"timeout"` + The canonical name of the agent that produced this item. - - `Exit object { exit_code, type }` + - `ProgramOutput object { id, call_id, result, 3 more }` - Indicates that the shell commands finished and returned an exit code. + - `id: string` - - `exit_code: number` + The unique ID of the program output item. - Exit code from the shell process. + - `call_id: string` - - `type: "exit"` + The call ID of the program item. - The outcome type. Always `exit`. + - `result: string` - - `"exit"` + The result produced by the program item. - - `stderr: string` + - `status: "completed" or "incomplete"` - The standard error output that was captured. + The terminal status of the program output item. - - `stdout: string` + - `"completed"` - The standard output that was captured. + - `"incomplete"` - - `created_by: optional string` + - `type: "program_output"` - The identifier of the actor that created the item. + The type of the item. Always `program_output`. - - `status: "in_progress" or "completed" or "incomplete"` + - `"program_output"` - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + - `agent: optional object { agent_name }` - - `"in_progress"` + The agent that produced this item. - - `"completed"` + - `agent_name: string` - - `"incomplete"` + The canonical name of the agent that produced this item. - - `type: "shell_call_output"` + - `ToolSearchCall object { id, arguments, call_id, 5 more }` - The type of the shell call output. Always `shell_call_output`. + - `id: string` - - `"shell_call_output"` + The unique ID of the tool search call item. - - `agent: optional object { agent_name }` + - `arguments: unknown` - The agent that produced this item. + Arguments used for the tool search call. - - `agent_name: string` + - `call_id: string` - The canonical name of the agent that produced this item. + The unique ID of the tool search call generated by the model. - - `caller: optional object { type } or object { caller_id, type }` + - `execution: "server" or "client"` - The execution context that produced this tool call. + Whether tool search was executed by the server or by the client. - - `Direct object { type }` + - `"server"` - - `type: "direct"` + - `"client"` - - `"direct"` + - `status: "in_progress" or "completed" or "incomplete"` - - `Program object { caller_id, type }` + The status of the tool search call item that was recorded. - - `caller_id: string` + - `"in_progress"` - The call ID of the program item that produced this tool call. + - `"completed"` - - `type: "program"` + - `"incomplete"` - - `"program"` + - `type: "tool_search_call"` - - `created_by: optional string` + The type of the item. Always `tool_search_call`. - The identifier of the actor that created the item. + - `"tool_search_call"` - - `ApplyPatchCall object { id, call_id, operation, 5 more }` + - `agent: optional object { agent_name }` - A tool call that applies file diffs by creating, deleting, or updating files. + The agent that produced this item. - - `id: string` + - `agent_name: string` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + The canonical name of the agent that produced this item. - - `call_id: string` + - `created_by: optional string` - The unique ID of the apply patch tool call generated by the model. + The identifier of the actor that created the item. - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + - `ToolSearchOutput object { id, call_id, execution, 5 more }` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + - `id: string` - - `CreateFile object { diff, path, type }` + The unique ID of the tool search output item. - Instruction describing how to create a file via the apply_patch tool. + - `call_id: string` - - `diff: string` + The unique ID of the tool search call generated by the model. - Diff to apply. + - `execution: "server" or "client"` - - `path: string` + Whether tool search was executed by the server or by the client. - Path of the file to create. + - `"server"` + + - `"client"` + + - `status: "in_progress" or "completed" or "incomplete"` - - `type: "create_file"` + The status of the tool search output item that was recorded. - 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. + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - - `path: string` + The loaded tool definitions returned by tool search. - Path of the file to delete. + - `Function object { name, parameters, strict, 5 more }` - - `type: "delete_file"` + 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). - Delete the specified file. + - `name: string` - - `"delete_file"` + The name of the function to call. - - `UpdateFile object { diff, path, type }` + - `parameters: map[unknown]` - Instruction describing how to update a file via the apply_patch tool. + A JSON schema object describing the parameters of the function. - - `diff: string` + - `strict: boolean` - Diff to apply. + Whether strict parameter validation is enforced for this function tool. - - `path: string` + - `type: "function"` - Path of the file to update. + The type of the function tool. Always `function`. - - `type: "update_file"` + - `"function"` - Update an existing file with the provided diff. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"update_file"` + The tool invocation context(s). - - `status: "in_progress" or "completed"` + - `"direct"` - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `"programmatic"` - - `"in_progress"` + - `defer_loading: optional boolean` - - `"completed"` + Whether this function is deferred and loaded via tool search. - - `type: "apply_patch_call"` + - `description: optional string` - The type of the item. Always `apply_patch_call`. + A description of the function. Used by the model to determine whether or not to call the function. - - `"apply_patch_call"` + - `output_schema: optional map[unknown]` - - `agent: optional object { agent_name }` + A JSON schema object describing the JSON value encoded in string outputs for this function. - The agent that produced this item. + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - - `agent_name: 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 canonical name of the agent that produced this item. + - `type: "file_search"` - - `caller: optional object { type } or object { caller_id, type }` + The type of the file search tool. Always `file_search`. - The execution context that produced this tool call. + - `"file_search"` - - `Direct object { type }` + - `vector_store_ids: array of string` - - `type: "direct"` + The IDs of the vector stores to search. - - `"direct"` + - `filters: optional object { key, type, value } or object { filters, type }` - - `Program object { caller_id, type }` + A filter to apply. - - `caller_id: string` + - `ComparisonFilter object { key, type, value }` - The call ID of the program item that produced this tool call. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `type: "program"` + - `key: string` - - `"program"` + The key to compare against the value. - - `created_by: optional string` + - `type: "eq" or "ne" or "gt" or 5 more` - The ID of the entity that created this tool call. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `ApplyPatchCallOutput object { id, call_id, status, 5 more }` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - The output emitted by an apply patch tool call. + - `"eq"` - - `id: string` + - `"ne"` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `"gt"` - - `call_id: string` + - `"gte"` - The unique ID of the apply patch tool call generated by the model. + - `"lt"` - - `status: "completed" or "failed"` + - `"lte"` - The status of the apply patch tool call output. One of `completed` or `failed`. + - `"in"` - - `"completed"` + - `"nin"` - - `"failed"` + - `value: string or number or boolean or array of string or number` - - `type: "apply_patch_call_output"` + The value to compare against the attribute key; supports string, number, or boolean types. - The type of the item. Always `apply_patch_call_output`. + - `string` - - `"apply_patch_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` - - `caller: optional object { type } or object { caller_id, type }` + - `CompoundFilter object { filters, type }` - The execution context that produced this tool call. + Combine multiple filters using `and` or `or`. - - `Direct object { type }` + - `filters: array of object { key, type, value } or unknown` - - `type: "direct"` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `"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` - - `"program"` + 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 ID of the entity that created this tool call output. + - `"eq"` - - `output: optional string` + - `"ne"` - Optional textual output returned by the apply patch tool. + - `"gt"` - - `McpCall object { id, arguments, name, 7 more }` + - `"gte"` - An invocation of a tool on an MCP server. + - `"lt"` - - `id: string` + - `"lte"` - The unique ID of the tool call. + - `"in"` - - `arguments: string` + - `"nin"` - A JSON string of the arguments passed to the tool. + - `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 tool that was run. + - `string` - - `server_label: string` + - `number` - The label of the MCP server running the tool. + - `boolean` - - `type: "mcp_call"` + - `array of string or number` - The type of the item. Always `mcp_call`. + - `string` - - `"mcp_call"` + - `number` - - `agent: optional object { agent_name }` + - `unknown` - The agent that produced this item. + - `type: "and" or "or"` - - `agent_name: string` + Type of operation: `and` or `or`. - The canonical name of the agent that produced this item. + - `"and"` - - `approval_request_id: optional string` + - `"or"` - 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. + - `max_num_results: optional number` - - `error: optional string` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - The error from the tool call, if any. + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `output: optional string` + Ranking options for search. - The output from the tool call. + - `hybrid_search: optional object { embedding_weight, text_weight }` - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `embedding_weight: number` - - `"in_progress"` + 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. - - `"calling"` + - `ranker: optional "auto" or "default-2024-11-15"` - - `"failed"` + The ranker to use for the file search. - - `McpListTools object { id, server_label, tools, 3 more }` + - `"auto"` - A list of tools available on an MCP server. + - `"default-2024-11-15"` - - `id: string` + - `score_threshold: optional number` - The unique ID of the list. + 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. - - `server_label: string` + - `Computer object { type }` - The label of the MCP server. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `tools: array of object { input_schema, name, annotations, description }` + - `type: "computer"` - The tools available on the server. + The type of the computer tool. Always `computer`. - - `input_schema: unknown` + - `"computer"` - The JSON schema describing the tool's input. + - `ComputerUsePreview object { display_height, display_width, environment, type }` - - `name: string` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The name of the tool. + - `display_height: number` - - `annotations: optional unknown` + The height of the computer display. - Additional annotations about the tool. + - `display_width: number` - - `description: optional string` + The width of the computer display. - The description of the tool. + - `environment: "windows" or "mac" or "linux" or 2 more` - - `type: "mcp_list_tools"` + The type of computer environment to control. - The type of the item. Always `mcp_list_tools`. + - `"windows"` - - `"mcp_list_tools"` + - `"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"` - - `error: optional string` + The type of the computer use tool. Always `computer_use_preview`. - Error message if the server could not list tools. + - `"computer_use_preview"` - - `McpApprovalRequest object { id, arguments, name, 3 more }` + - `WebSearch object { type, filters, search_context_size, user_location }` - A request for human approval of a tool invocation. + 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 approval request. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `arguments: string` + - `"web_search"` - A JSON string of arguments for the tool. + - `"web_search_2025_08_26"` - - `name: string` + - `filters: optional object { allowed_domains }` - The name of the tool to run. + Filters for the search. - - `server_label: string` + - `allowed_domains: optional array of string` - The label of the MCP server making the request. + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `type: "mcp_approval_request"` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - The type of the item. Always `mcp_approval_request`. + - `search_context_size: optional "low" or "medium" or "high"` - - `"mcp_approval_request"` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `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 }` - - `McpApprovalResponse object { id, approval_request_id, approve, 3 more }` + The approximate location of the user. - A response to an MCP approval request. + - `city: optional string` - - `id: string` + Free text input for the city of the user, e.g. `San Francisco`. - The unique ID of the approval response + - `country: optional string` - - `approval_request_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 approval request being answered. + - `region: optional string` - - `approve: boolean` + Free text input for the region of the user, e.g. `California`. - Whether the request was approved. + - `timezone: optional string` - - `type: "mcp_approval_response"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The type of the item. Always `mcp_approval_response`. + - `type: optional "approximate"` - - `"mcp_approval_response"` + The type of location approximation. Always `approximate`. - - `agent: optional object { agent_name }` + - `"approximate"` - The agent that produced this item. + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `agent_name: 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 canonical name of the agent that produced this item. + - `server_label: string` - - `reason: optional string` + A label for this MCP server, used to identify it in tool calls. - Optional reason for the decision. + - `type: "mcp"` - - `CustomToolCall object { call_id, input, name, 5 more }` + The type of the MCP tool. Always `mcp`. - A call to a custom tool created by the model. + - `"mcp"` - - `call_id: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - An identifier used to map this custom tool call to a tool call output. + The tool invocation context(s). - - `input: string` + - `"direct"` - The input for the custom tool call generated by the model. + - `"programmatic"` - - `name: string` + - `allowed_tools: optional array of string or object { read_only, tool_names }` - The name of the custom tool being called. + List of allowed tool names or a filter object. - - `type: "custom_tool_call"` + - `McpAllowedTools = array of string` - The type of the custom tool call. Always `custom_tool_call`. + A string array of allowed tool names - - `"custom_tool_call"` + - `McpToolFilter object { read_only, tool_names }` - - `id: optional string` + A filter object to specify which tools are allowed. - The unique ID of the custom tool call in the OpenAI platform. + - `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` - - `caller: optional object { type } or 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. - The execution context that produced this tool call. + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `Direct object { 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). - - `type: "direct"` + Currently supported `connector_id` values are: - - `"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` - - `Program object { caller_id, type }` + - `"connector_dropbox"` - - `caller_id: string` + - `"connector_gmail"` - The call ID of the program item that produced this tool call. + - `"connector_googlecalendar"` - - `type: "program"` + - `"connector_googledrive"` - - `"program"` + - `"connector_microsoftteams"` - - `namespace: optional string` + - `"connector_outlookcalendar"` - The namespace of the custom tool being called. + - `"connector_outlookemail"` - - `CustomToolCallOutput object { id, call_id, output, 5 more }` + - `"connector_sharepoint"` - - `id: string` + - `defer_loading: optional boolean` - The unique ID of the custom tool call output item. + Whether this MCP tool is deferred and discovered via tool search. - - `call_id: string` + - `headers: optional map[string]` - The call ID, used to map this custom tool call output to a custom tool call. + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `require_approval: optional object { always, never } or "always" or "never"` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + Specify which of the MCP server's tools require approval. - - `StringOutput = string` + - `McpToolApprovalFilter object { always, never }` - A string of the output of the custom tool call. + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `always: optional object { read_only, tool_names }` - Text, image, or file output of the custom tool call. + 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. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `tool_names: optional array of string` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + List of allowed tool names. - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `never: optional object { read_only, tool_names }` - A file input to the model. + A filter object to specify which tools are allowed. - - `status: "in_progress" or "completed" or "incomplete"` + - `read_only: optional boolean` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `"in_progress"` + - `tool_names: optional array of string` - - `"completed"` + List of allowed tool names. - - `"incomplete"` + - `McpToolApprovalSetting = "always" or "never"` - - `type: "custom_tool_call_output"` + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - The type of the custom tool call output. Always `custom_tool_call_output`. + - `"always"` - - `"custom_tool_call_output"` + - `"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. - - `caller: optional object { type } or object { caller_id, type }` + - `tunnel_id: optional string` - The execution context 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. - - `Direct object { type }` + - `CodeInterpreter object { container, type, allowed_callers }` - - `type: "direct"` + A tool that runs Python code to help generate a response to a prompt. - The caller type. Always `direct`. + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `"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. - - `Program object { caller_id, type }` + - `string` - - `caller_id: string` + The container ID. - The call ID of the program item that produced this tool call. + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - - `type: "program"` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - The caller type. Always `program`. + - `type: "auto"` - - `"program"` + Always `auto`. - - `created_by: optional string` + - `"auto"` - The identifier of the actor that created the item. + - `file_ids: optional array of string` -### Beta Response Output Item Added Event + An optional list of uploaded files to make available to your code. -- `BetaResponseOutputItemAddedEvent object { item, output_index, sequence_number, 2 more }` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - Emitted when a new output item is added. + The memory limit for the code interpreter container. - - `item: BetaResponseOutputItem` + - `"1g"` - The output item that was added. + - `"4g"` - - `BetaResponseOutputMessage object { id, content, role, 4 more }` + - `"16g"` - An output message from the model. + - `"64g"` - - `id: string` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - The unique ID of the output message. + Network access policy for the container. - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + - `BetaContainerNetworkPolicyDisabled object { type }` - The content of the output message. + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `BetaResponseOutputText object { annotations, text, type, logprobs }` + - `type: "code_interpreter"` - A text output from the model. + The type of the code interpreter tool. Always `code_interpreter`. - - `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 }` + - `"code_interpreter"` - The annotations of the text output. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `FileCitation object { file_id, filename, index, type }` + The tool invocation context(s). - A citation to a file. + - `"direct"` - - `file_id: string` + - `"programmatic"` - The ID of the file. + - `ProgrammaticToolCalling object { type }` - - `filename: string` + - `type: "programmatic_tool_calling"` - The filename of the file cited. + The type of the tool. Always `programmatic_tool_calling`. - - `index: number` + - `"programmatic_tool_calling"` - The index of the file in the list of files. + - `ImageGeneration object { type, action, background, 9 more }` - - `type: "file_citation"` + A tool that generates images using the GPT image models. - The type of the file citation. Always `file_citation`. + - `type: "image_generation"` - - `"file_citation"` + The type of the image generation tool. Always `image_generation`. - - `URLCitation object { end_index, start_index, title, 2 more }` + - `"image_generation"` - A citation for a web resource used to generate a model response. + - `action: optional "generate" or "edit" or "auto"` - - `end_index: number` + Whether to generate a new image or edit an existing image. Default: `auto`. - The index of the last character of the URL citation in the message. + - `"generate"` - - `start_index: number` + - `"edit"` - The index of the first character of the URL citation in the message. + - `"auto"` - - `title: string` + - `background: optional "transparent" or "opaque" or "auto"` - The title of the web resource. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - - `type: "url_citation"` + - `"transparent"` - The type of the URL citation. Always `url_citation`. + - `"opaque"` - - `"url_citation"` + - `"auto"` - - `url: string` + - `input_fidelity: optional "high" or "low"` - The URL of the web resource. + 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`. - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + - `"high"` - A citation for a container file used to generate a model response. + - `"low"` - - `container_id: string` + - `input_image_mask: optional object { file_id, image_url }` - The ID of the container file. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `end_index: number` + - `file_id: optional string` - The index of the last character of the container file citation in the message. + File ID for the mask image. - - `file_id: string` + - `image_url: optional string` - The ID of the file. + Base64-encoded mask image. - - `filename: string` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - The filename of the container file cited. + The image generation model to use. Default: `gpt-image-1`. - - `start_index: number` + - `string` - The index of the first character of the container file citation in the message. + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `type: "container_file_citation"` + The image generation model to use. Default: `gpt-image-1`. - The type of the container file citation. Always `container_file_citation`. + - `"gpt-image-1"` - - `"container_file_citation"` + - `"gpt-image-1-mini"` - - `FilePath object { file_id, index, type }` + - `"gpt-image-1.5"` - A path to a file. + - `moderation: optional "auto" or "low"` - - `file_id: string` + Moderation level for the generated image. Default: `auto`. - The ID of the file. + - `"auto"` - - `index: number` + - `"low"` - The index of the file in the list of files. + - `output_compression: optional number` - - `type: "file_path"` + Compression level for the output image. Default: 100. - The type of the file path. Always `file_path`. + - `output_format: optional "png" or "webp" or "jpeg"` - - `"file_path"` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `text: string` + - `"png"` - The text output from the model. + - `"webp"` - - `type: "output_text"` + - `"jpeg"` - The type of the output text. Always `output_text`. + - `partial_images: optional number` - - `"output_text"` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + - `quality: optional "low" or "medium" or "high" or "auto"` - - `token: string` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `bytes: array of number` + - `"low"` - - `logprob: number` + - `"medium"` - - `top_logprobs: array of object { token, bytes, logprob }` + - `"high"` - - `token: string` + - `"auto"` - - `bytes: array of number` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `logprob: 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`. - - `BetaResponseOutputRefusal object { refusal, type }` + - `string` - A refusal from the model. + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `refusal: 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 refusal explanation from the model. + - `"1024x1024"` - - `type: "refusal"` + - `"1024x1536"` - The type of the refusal. Always `refusal`. + - `"1536x1024"` - - `"refusal"` + - `"auto"` - - `role: "assistant"` + - `LocalShell object { type }` - The role of the output message. Always `assistant`. + A tool that allows the model to execute shell commands in a local environment. - - `"assistant"` + - `type: "local_shell"` - - `status: "in_progress" or "completed" or "incomplete"` + The type of the local shell tool. Always `local_shell`. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `"local_shell"` - - `"in_progress"` + - `Shell object { type, allowed_callers, environment }` - - `"completed"` + A tool that allows the model to execute shell commands. - - `"incomplete"` + - `type: "shell"` - - `type: "message"` + The type of the shell tool. Always `shell`. - The type of the output message. Always `message`. + - `"shell"` - - `"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. + - `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. + - `BetaLocalEnvironment object { type, skills }` - - `"commentary"` + - `BetaContainerReference object { container_id, type }` - - `"final_answer"` + - `Custom object { name, type, allowed_callers, 3 more }` - - `FileSearchCall object { id, queries, status, 3 more }` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `name: string` - - `id: string` + The name of the custom tool, used to identify it in tool calls. - The unique ID of the file search tool call. + - `type: "custom"` - - `queries: array of string` + The type of the custom tool. Always `custom`. - The queries used to search for files. + - `"custom"` - - `status: "in_progress" or "searching" or "completed" or 2 more` + - `allowed_callers: optional array of "direct" or "programmatic"` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + The tool invocation context(s). - - `"in_progress"` + - `"direct"` - - `"searching"` + - `"programmatic"` - - `"completed"` + - `defer_loading: optional boolean` - - `"incomplete"` + Whether this tool should be deferred and discovered via tool search. - - `"failed"` + - `description: optional string` - - `type: "file_search_call"` + Optional description of the custom tool, used to provide more context. - The type of the file search tool call. Always `file_search_call`. + - `format: optional object { type } or object { definition, syntax, type }` - - `"file_search_call"` + 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`. - - `results: optional array of object { attributes, file_id, filename, 2 more }` + - `"text"` - The results of the file search tool call. + - `Grammar object { definition, syntax, type }` - - `attributes: optional map[string or number or boolean]` + A grammar defined by the user. - 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. + - `definition: string` - - `string` + The grammar definition. - - `number` + - `syntax: "lark" or "regex"` - - `boolean` + The syntax of the grammar definition. One of `lark` or `regex`. - - `file_id: optional string` + - `"lark"` - The unique ID of the file. + - `"regex"` - - `filename: optional string` + - `type: "grammar"` - The name of the file. + Grammar format. Always `grammar`. - - `score: optional number` + - `"grammar"` - The relevance score of the file - a value between 0 and 1. + - `Namespace object { description, name, tools, type }` - - `text: optional string` + Groups function/custom tools under a shared namespace. - The text that was retrieved from the file. + - `description: string` - - `FunctionCall object { arguments, call_id, name, 6 more }` + A description of the namespace shown to the model. - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `name: string` - - `arguments: string` + The namespace name used in tool calls (for example, `crm`). - A JSON string of the arguments to pass to the function. + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - - `call_id: string` + The function/custom tools available inside this namespace. - The unique ID of the function tool call generated by the model. + - `Function object { name, type, allowed_callers, 5 more }` - `name: string` - The name of the function to run. + - `type: "function"` - - `type: "function_call"` + - `"function"` - The type of the function tool call. Always `function_call`. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"function_call"` + The tool invocation context(s). - - `id: optional string` + - `"direct"` - The unique ID of the function tool call. + - `"programmatic"` - - `agent: optional object { agent_name }` + - `defer_loading: optional boolean` - The agent that produced this item. + Whether this function should be deferred and discovered via tool search. - - `agent_name: string` + - `description: optional string` - The canonical name of the agent that produced this item. + - `output_schema: optional map[unknown]` - - `caller: optional object { type } or object { caller_id, type }` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - The execution context that produced this tool call. + - `parameters: optional unknown` - - `Direct object { type }` + - `strict: optional boolean` - - `type: "direct"` + 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. - - `"direct"` + - `Custom object { name, type, allowed_callers, 3 more }` - - `Program object { caller_id, type }` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `caller_id: string` + - `name: string` - The call ID of the program item that produced this tool call. + The name of the custom tool, used to identify it in tool calls. - - `type: "program"` + - `type: "custom"` - - `"program"` + The type of the custom tool. Always `custom`. - - `namespace: optional string` + - `"custom"` - 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"` + - `defer_loading: optional boolean` - - `"incomplete"` + Whether this tool should be deferred and discovered via tool search. - - `FunctionCallOutput object { id, call_id, output, 5 more }` + - `description: optional string` - - `id: string` + Optional description of the custom tool, used to provide more context. - The unique ID of the function call tool output. + - `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 function tool call generated by the model. + - `Text object { type }` - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + Unconstrained free-form text. - The output from the function call generated by your code. - Can be a string or an list of output content. + - `type: "text"` - - `StringOutput = string` + Unconstrained text format. Always `text`. - A string of the output of the function call. + - `"text"` - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `Grammar object { definition, syntax, type }` - Text, image, or file output of the function call. + A grammar defined by the user. - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `definition: string` - A text input to the model. + The grammar definition. - - `text: string` + - `syntax: "lark" or "regex"` - The text input to the model. + The syntax of the grammar definition. One of `lark` or `regex`. - - `type: "input_text"` + - `"lark"` - The type of the input item. Always `input_text`. + - `"regex"` - - `"input_text"` + - `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"` + - `type: "namespace"` - The breakpoint mode. Always `explicit`. + The type of the tool. Always `namespace`. - - `"explicit"` + - `"namespace"` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `ToolSearch object { type, description, execution, parameters }` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + Hosted or BYOT tool search configuration for deferred tools. - - `detail: "low" or "high" or "auto" or "original"` + - `type: "tool_search"` - 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 tool. Always `tool_search`. - - `"low"` + - `"tool_search"` - - `"high"` + - `description: optional string` - - `"auto"` + Description shown to the model for a client-executed tool search tool. - - `"original"` + - `execution: optional "server" or "client"` - - `type: "input_image"` + Whether tool search is executed by the server or by the client. - The type of the input item. Always `input_image`. + - `"server"` - - `"input_image"` + - `"client"` - - `file_id: optional string` + - `parameters: optional unknown` - The ID of the file to be sent to the model. + Parameter schema for a client-executed tool search tool. - - `image_url: optional string` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data 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). - - `prompt_cache_breakpoint: optional object { mode }` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - Marks the exact end of a reusable 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 web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `mode: "explicit"` + - `"web_search_preview"` - The breakpoint mode. Always `explicit`. + - `"web_search_preview_2025_03_11"` - - `"explicit"` + - `search_content_types: optional array of "text" or "image"` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `"text"` - A file input to the model. + - `"image"` - - `type: "input_file"` + - `search_context_size: optional "low" or "medium" or "high"` - The type of the input item. Always `input_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. - - `"input_file"` + - `"low"` - - `detail: optional "auto" or "low" or "high"` + - `"medium"` - 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`. + - `"high"` - - `"auto"` + - `user_location: optional object { type, city, country, 2 more }` - - `"low"` + The user's location. - - `"high"` + - `type: "approximate"` - - `file_data: optional string` + The type of location approximation. Always `approximate`. - The content of the file to be sent to the model. + - `"approximate"` - - `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"` + - `ApplyPatch object { type, allowed_callers }` - The breakpoint mode. Always `explicit`. + Allows the assistant to create, delete, or update files using unified diffs. - - `"explicit"` + - `type: "apply_patch"` - - `status: "in_progress" or "completed" or "incomplete"` + The type of the tool. 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"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"completed"` + The tool invocation context(s). - - `"incomplete"` + - `"direct"` - - `type: "function_call_output"` + - `"programmatic"` - The type of the function tool call output. Always `function_call_output`. + - `type: "tool_search_output"` - - `"function_call_output"` + The type of the item. Always `tool_search_output`. + + - `"tool_search_output"` - `agent: optional object { agent_name }` @@ -155148,2173 +154243,2195 @@ 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 }` + - `created_by: optional string` - The execution context that produced this tool call. + 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"` - - `Direct object { type }` + - `"assistant"` - - `type: "direct"` + - `"system"` - The caller type. Always `direct`. + - `"critic"` - - `"direct"` + - `"discriminator"` - - `Program object { caller_id, type }` + - `"developer"` - - `caller_id: string` + - `"tool"` - The call ID of the program item that produced this 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` - - `type: "program"` + The additional tool definitions made available at this item. - The caller type. Always `program`. + - `Function object { name, parameters, strict, 5 more }` - - `"program"` + 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). - - `created_by: optional string` + - `name: string` - The identifier of the actor that created the item. + The name of the function to call. - - `AgentMessage object { id, author, content, 3 more }` + - `parameters: map[unknown]` - - `id: string` + A JSON schema object describing the parameters of the function. - The unique ID of the agent message. + - `strict: boolean` - - `author: string` + Whether strict parameter validation is enforced for this function tool. - The sending agent identity. + - `type: "function"` - - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` + The type of the function tool. Always `function`. - Encrypted content sent between agents. + - `"function"` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `allowed_callers: optional array of "direct" or "programmatic"` - A text input to the model. + The tool invocation context(s). - - `BetaResponseOutputText object { annotations, text, type, logprobs }` + - `"direct"` - A text output from the model. + - `"programmatic"` - - `Text object { text, type }` + - `defer_loading: optional boolean` - A text content. + Whether this function is deferred and loaded via tool search. - - `text: string` + - `description: optional string` - - `type: "text"` + A description of the function. Used by the model to determine whether or not to call the function. - - `"text"` + - `output_schema: optional map[unknown]` - - `SummaryText object { text, type }` + A JSON schema object describing the JSON value encoded in string outputs for this function. - A summary text from the model. + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - - `text: string` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - A summary of the reasoning output from the model so far. + - `type: "file_search"` - - `type: "summary_text"` + The type of the file search tool. Always `file_search`. - The type of the object. Always `summary_text`. + - `"file_search"` - - `"summary_text"` + - `vector_store_ids: array of string` - - `ReasoningText object { text, type }` + The IDs of the vector stores to search. - Reasoning text from the model. + - `filters: optional object { key, type, value } or object { filters, type }` - - `text: string` + A filter to apply. - The reasoning text from the model. + - `ComparisonFilter object { key, type, value }` - - `type: "reasoning_text"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The type of the reasoning text. Always `reasoning_text`. + - `key: string` - - `"reasoning_text"` + The key to compare against the value. - - `BetaResponseOutputRefusal object { refusal, type }` + - `type: "eq" or "ne" or "gt" or 5 more` - A refusal from the model. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `BetaResponseInputImage object { detail, type, file_id, 2 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 - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `"eq"` - - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` + - `"ne"` - A screenshot of a computer. + - `"gt"` - - `detail: "low" or "high" or "auto" or "original"` + - `"gte"` - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `"lt"` - - `"low"` + - `"lte"` - - `"high"` + - `"in"` - - `"auto"` + - `"nin"` - - `"original"` + - `value: string or number or boolean or array of string or number` - - `file_id: string` + The value to compare against the attribute key; supports string, number, or boolean types. - The identifier of an uploaded file that contains the screenshot. + - `string` - - `image_url: string` + - `number` - The URL of the screenshot image. + - `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` - - `prompt_cache_breakpoint: optional object { mode }` + - `CompoundFilter 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. + Combine multiple filters using `and` or `or`. - - `mode: "explicit"` + - `filters: array of object { key, type, value } or unknown` - The breakpoint mode. Always `explicit`. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `"explicit"` + - `ComparisonFilter object { key, type, value }` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - A file input to the model. + - `key: string` - - `EncryptedContent object { encrypted_content, type }` + The key to compare against the value. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `type: "eq" or "ne" or "gt" or 5 more` - - `encrypted_content: string` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - Opaque encrypted 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 - - `type: "encrypted_content"` + - `"eq"` - The type of the input item. Always `encrypted_content`. + - `"ne"` - - `"encrypted_content"` + - `"gt"` - - `recipient: string` + - `"gte"` - The destination agent identity. + - `"lt"` - - `type: "agent_message"` + - `"lte"` - The type of the item. Always `agent_message`. + - `"in"` - - `"agent_message"` + - `"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` - - `MultiAgentCall object { id, action, arguments, 3 more }` + - `boolean` - - `id: string` + - `array of string or number` - The unique ID of the multi-agent call item. + - `string` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `number` - The multi-agent action to execute. + - `unknown` - - `"spawn_agent"` + - `type: "and" or "or"` - - `"interrupt_agent"` + Type of operation: `and` or `or`. - - `"list_agents"` + - `"and"` - - `"send_message"` + - `"or"` - - `"followup_task"` + - `max_num_results: optional number` - - `"wait_agent"` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `arguments: string` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - The JSON string of arguments generated for the action. + Ranking options for search. - - `call_id: string` + - `hybrid_search: optional object { embedding_weight, text_weight }` - The unique ID linking this call to its output. + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `type: "multi_agent_call"` + - `embedding_weight: number` - The type of the multi-agent call. Always `multi_agent_call`. + The weight of the embedding in the reciprocal ranking fusion. - - `"multi_agent_call"` + - `text_weight: number` - - `agent: optional object { agent_name }` + The weight of the text in the reciprocal ranking fusion. - The agent that produced this item. + - `ranker: optional "auto" or "default-2024-11-15"` - - `agent_name: string` + The ranker to use for the file search. - The canonical name of the agent that produced this item. + - `"auto"` - - `MultiAgentCallOutput object { id, action, call_id, 3 more }` + - `"default-2024-11-15"` - - `id: string` + - `score_threshold: optional number` - The unique ID of the multi-agent call output 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. - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `Computer object { type }` - The multi-agent action that produced this result. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"spawn_agent"` + - `type: "computer"` - - `"interrupt_agent"` + The type of the computer tool. Always `computer`. - - `"list_agents"` + - `"computer"` - - `"send_message"` + - `ComputerUsePreview object { display_height, display_width, environment, type }` - - `"followup_task"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"wait_agent"` + - `display_height: number` - - `call_id: string` + The height of the computer display. - The unique ID of the multi-agent call. + - `display_width: number` - - `output: array of BetaResponseOutputText` + The width of the computer display. - Text output returned by the multi-agent action. + - `environment: "windows" or "mac" or "linux" or 2 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 }` + The type of computer environment to control. - The annotations of the text output. + - `"windows"` - - `text: string` + - `"mac"` - The text output from the model. + - `"linux"` - - `type: "output_text"` + - `"ubuntu"` - The type of the output text. Always `output_text`. + - `"browser"` - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + - `type: "computer_use_preview"` - - `type: "multi_agent_call_output"` + The type of the computer use tool. Always `computer_use_preview`. - The type of the multi-agent result. Always `multi_agent_call_output`. + - `"computer_use_preview"` - - `"multi_agent_call_output"` + - `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 produced this item. + - `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"` - - `WebSearchCall object { id, action, status, 2 more }` + - `"web_search_2025_08_26"` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `filters: optional object { allowed_domains }` - - `id: string` + Filters for the search. - The unique ID of the web search tool call. + - `allowed_domains: optional array of string` - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - 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). + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `Search object { type, queries, query, sources }` + - `search_context_size: optional "low" or "medium" or "high"` - Action type "search" - Performs a web search query. + 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: "search"` + - `"low"` - The action type. + - `"medium"` - - `"search"` + - `"high"` - - `queries: optional array of string` + - `user_location: optional object { city, country, region, 2 more }` - The search queries. + The approximate location of the user. - - `query: optional string` + - `city: optional string` - The search query. + Free text input for the city of the user, e.g. `San Francisco`. - - `sources: optional array of object { type, url }` + - `country: optional string` - The sources used in the search. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `type: "url"` + - `region: optional string` - The type of source. Always `url`. + Free text input for the region of the user, e.g. `California`. - - `"url"` + - `timezone: optional string` - - `url: string` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The URL of the source. + - `type: optional "approximate"` - - `OpenPage object { type, url }` + The type of location approximation. Always `approximate`. - Action type "open_page" - Opens a specific URL from search results. + - `"approximate"` - - `type: "open_page"` + - `Mcp object { server_label, type, allowed_callers, 9 more }` - The action type. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - - `"open_page"` + - `server_label: string` - - `url: optional string` + A label for this MCP server, used to identify it in tool calls. - The URL opened by the model. + - `type: "mcp"` - - `FindInPage object { pattern, type, url }` + The type of the MCP tool. Always `mcp`. - Action type "find_in_page": Searches for a pattern within a loaded page. + - `"mcp"` - - `pattern: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The pattern or text to search for within the page. + The tool invocation context(s). - - `type: "find_in_page"` + - `"direct"` - The action type. + - `"programmatic"` - - `"find_in_page"` + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `url: string` + List of allowed tool names or a filter object. - The URL of the page searched for the pattern. + - `McpAllowedTools = array of string` - - `status: "in_progress" or "searching" or "completed" or "failed"` + A string array of allowed tool names - The status of the web search tool call. + - `McpToolFilter object { read_only, tool_names }` - - `"in_progress"` + A filter object to specify which tools are allowed. - - `"searching"` + - `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. - - `"failed"` + - `tool_names: optional array of string` - - `type: "web_search_call"` + List of allowed tool names. - The type of the web search tool call. Always `web_search_call`. + - `authorization: optional string` - - `"web_search_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. - - `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` - - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` + - `"connector_dropbox"` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + - `"connector_gmail"` - - `id: string` + - `"connector_googlecalendar"` - The unique ID of the computer call. + - `"connector_googledrive"` - - `call_id: string` + - `"connector_microsoftteams"` - An identifier used when responding to the tool call with output. + - `"connector_outlookcalendar"` - - `pending_safety_checks: array of object { id, code, message }` + - `"connector_outlookemail"` - The pending safety checks for the computer call. + - `"connector_sharepoint"` - - `id: string` + - `defer_loading: optional boolean` - The ID of the pending safety check. + Whether this MCP tool is deferred and discovered via tool search. - - `code: optional string` + - `headers: optional map[string]` - The type of the pending safety check. + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `message: optional string` + - `require_approval: optional object { always, never } or "always" or "never"` - Details about the pending safety check. + Specify which of the MCP server's tools require approval. - - `status: "in_progress" or "completed" or "incomplete"` + - `McpToolApprovalFilter object { always, never }` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `"in_progress"` + - `always: optional object { read_only, tool_names }` - - `"completed"` + A filter object to specify which tools are allowed. - - `"incomplete"` + - `read_only: optional boolean` - - `type: "computer_call"` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - The type of the computer call. Always `computer_call`. + - `tool_names: optional array of string` - - `"computer_call"` + List of allowed tool names. - - `action: optional BetaComputerAction` + - `never: optional object { read_only, tool_names }` - A click action. + A filter object to specify which tools are allowed. - - `Click object { button, type, x, 2 more }` + - `read_only: optional boolean` - A click action. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `button: "left" or "right" or "wheel" or 2 more` + - `tool_names: optional array of string` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + List of allowed tool names. - - `"left"` + - `McpToolApprovalSetting = "always" or "never"` - - `"right"` + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - - `"wheel"` + - `"always"` - - `"back"` + - `"never"` - - `"forward"` + - `server_description: optional string` - - `type: "click"` + Optional description of the MCP server, used to provide more context. - Specifies the event type. For a click action, this property is always `click`. + - `server_url: optional string` - - `"click"` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `x: number` + - `tunnel_id: optional string` - The x-coordinate where the click occurred. + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `y: number` + - `CodeInterpreter object { container, type, allowed_callers }` - The y-coordinate where the click occurred. + A tool that runs Python code to help generate a response to a prompt. - - `keys: optional array of string` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - The keys being held while clicking. + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - - `DoubleClick object { keys, type, x, y }` + - `string` - A double click action. + The container ID. - - `keys: array of string` + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - The keys being held while double-clicking. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `type: "double_click"` + - `type: "auto"` - Specifies the event type. For a double click action, this property is always set to `double_click`. + Always `auto`. - - `"double_click"` + - `"auto"` - - `x: number` + - `file_ids: optional array of string` - The x-coordinate where the double click occurred. + An optional list of uploaded files to make available to your code. - - `y: number` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - The y-coordinate where the double click occurred. + The memory limit for the code interpreter container. - - `Drag object { path, type, keys }` + - `"1g"` - A drag action. + - `"4g"` - - `path: array of object { x, y }` + - `"16g"` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `"64g"` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `x: number` + Network access policy for the container. - The x-coordinate. + - `BetaContainerNetworkPolicyDisabled object { type }` - - `y: number` + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - The y-coordinate. + - `type: "code_interpreter"` - - `type: "drag"` + The type of the code interpreter tool. Always `code_interpreter`. - Specifies the event type. For a drag action, this property is always set to `drag`. + - `"code_interpreter"` - - `"drag"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `keys: optional array of string` + The tool invocation context(s). - The keys being held while dragging the mouse. + - `"direct"` - - `Keypress object { keys, type }` + - `"programmatic"` - A collection of keypresses the model would like to perform. + - `ProgrammaticToolCalling object { type }` - - `keys: array of string` + - `type: "programmatic_tool_calling"` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + The type of the tool. Always `programmatic_tool_calling`. - - `type: "keypress"` + - `"programmatic_tool_calling"` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `ImageGeneration object { type, action, background, 9 more }` - - `"keypress"` + A tool that generates images using the GPT image models. - - `Move object { type, x, y, keys }` + - `type: "image_generation"` - A mouse move action. + The type of the image generation tool. Always `image_generation`. - - `type: "move"` + - `"image_generation"` - Specifies the event type. For a move action, this property is always set to `move`. + - `action: optional "generate" or "edit" or "auto"` - - `"move"` + Whether to generate a new image or edit an existing image. Default: `auto`. - - `x: number` + - `"generate"` - The x-coordinate to move to. + - `"edit"` - - `y: number` + - `"auto"` - The y-coordinate to move to. + - `background: optional "transparent" or "opaque" or "auto"` - - `keys: optional array of string` + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - The keys being held while moving the mouse. + - `"transparent"` - - `Screenshot object { type }` + - `"opaque"` - A screenshot action. + - `"auto"` - - `type: "screenshot"` + - `input_fidelity: optional "high" or "low"` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - - `"screenshot"` + - `"high"` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `"low"` - A scroll action. + - `input_image_mask: optional object { file_id, image_url }` - - `scroll_x: number` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - The horizontal scroll distance. + - `file_id: optional string` - - `scroll_y: number` + File ID for the mask image. - The vertical scroll distance. + - `image_url: optional string` - - `type: "scroll"` + Base64-encoded mask image. - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `"scroll"` + The image generation model to use. Default: `gpt-image-1`. - - `x: number` + - `string` - The x-coordinate where the scroll occurred. + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `y: number` + The image generation model to use. Default: `gpt-image-1`. - The y-coordinate where the scroll occurred. + - `"gpt-image-1"` - - `keys: optional array of string` + - `"gpt-image-1-mini"` - The keys being held while scrolling. + - `"gpt-image-1.5"` - - `Type object { text, type }` + - `moderation: optional "auto" or "low"` - An action to type in text. + Moderation level for the generated image. Default: `auto`. - - `text: string` + - `"auto"` - The text to type. + - `"low"` - - `type: "type"` + - `output_compression: optional number` - Specifies the event type. For a type action, this property is always set to `type`. + Compression level for the output image. Default: 100. - - `"type"` + - `output_format: optional "png" or "webp" or "jpeg"` - - `Wait object { type }` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - A wait action. + - `"png"` - - `type: "wait"` + - `"webp"` - Specifies the event type. For a wait action, this property is always set to `wait`. + - `"jpeg"` - - `"wait"` + - `partial_images: optional number` - - `actions: optional BetaComputerActionList` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `quality: optional "low" or "medium" or "high" or "auto"` - - `Click object { button, type, x, 2 more }` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - A click action. + - `"low"` - - `DoubleClick object { keys, type, x, y }` + - `"medium"` - A double click action. + - `"high"` - - `Drag object { path, type, keys }` + - `"auto"` - A drag action. + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `Keypress object { keys, type }` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - A collection of keypresses the model would like to perform. + - `string` - - `Move object { type, x, y, keys }` + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - A mouse move action. + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `Screenshot object { type }` + - `"1024x1024"` - A screenshot action. + - `"1024x1536"` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `"1536x1024"` - A scroll action. + - `"auto"` - - `Type object { text, type }` + - `LocalShell object { type }` - An action to type in text. + A tool that allows the model to execute shell commands in a local environment. - - `Wait object { type }` + - `type: "local_shell"` - A wait action. + The type of the local shell tool. Always `local_shell`. - - `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"` - - `ComputerCallOutput object { id, call_id, output, 5 more }` + The type of the shell tool. Always `shell`. - - `id: string` + - `"shell"` - The unique ID of the computer call tool output. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `call_id: string` + The tool invocation context(s). - The ID of the computer tool call that produced the output. + - `"direct"` - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `"programmatic"` - A computer screenshot image used with the computer use tool. + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - `type: "computer_screenshot"` + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `BetaLocalEnvironment object { type, skills }` - - `"computer_screenshot"` + - `BetaContainerReference object { container_id, type }` - - `file_id: optional string` + - `Custom object { name, type, allowed_callers, 3 more }` - The identifier of an uploaded file that contains the screenshot. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `image_url: optional string` + - `name: string` - The URL of the screenshot image. + The name of the custom tool, used to identify it in tool calls. - - `status: "completed" or "incomplete" or "failed" or "in_progress"` + - `type: "custom"` - 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 custom tool. Always `custom`. - - `"completed"` + - `"custom"` - - `"incomplete"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"failed"` + The tool invocation context(s). - - `"in_progress"` + - `"direct"` - - `type: "computer_call_output"` + - `"programmatic"` - The type of the computer tool call output. Always `computer_call_output`. + - `defer_loading: optional boolean` - - `"computer_call_output"` + Whether this tool should be deferred and discovered via tool search. - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `description: optional string` - The safety checks reported by the API that have been acknowledged by the - developer. + Optional description of the custom tool, used to provide more context. - - `id: string` + - `format: optional object { type } or object { definition, syntax, type }` - The ID of the pending safety check. + The input format for the custom tool. Default is unconstrained text. - - `code: optional string` + - `Text object { type }` - The type of the pending safety check. + Unconstrained free-form text. - - `message: optional string` + - `type: "text"` - Details about the pending safety check. + 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` - - `created_by: optional string` + The grammar definition. - The identifier of the actor that created the item. + - `syntax: "lark" or "regex"` - - `Reasoning object { id, summary, type, 4 more }` + The syntax of the grammar definition. One of `lark` or `regex`. - 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](https://platform.openai.com/docs/guides/conversation-state). + - `"lark"` - - `id: string` + - `"regex"` - The unique identifier of the reasoning content. + - `type: "grammar"` - - `summary: array of object { text, type }` + Grammar format. Always `grammar`. - Reasoning summary content. + - `"grammar"` - - `text: string` + - `Namespace object { description, name, tools, type }` - A summary of the reasoning output from the model so far. + Groups function/custom tools under a shared namespace. - - `type: "summary_text"` + - `description: string` - The type of the object. Always `summary_text`. + A description of the namespace shown to the model. - - `"summary_text"` + - `name: string` - - `type: "reasoning"` + The namespace name used in tool calls (for example, `crm`). - The type of the object. Always `reasoning`. + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - - `"reasoning"` + 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"` - - `content: optional array of object { text, type }` + - `allowed_callers: optional array of "direct" or "programmatic"` - Reasoning text content. + The tool invocation context(s). - - `text: string` + - `"direct"` - The reasoning text from the model. + - `"programmatic"` - - `type: "reasoning_text"` + - `defer_loading: optional boolean` - The type of the reasoning text. Always `reasoning_text`. + Whether this function should be deferred and discovered via tool search. - - `"reasoning_text"` + - `description: optional string` - - `encrypted_content: optional string` + - `output_schema: optional map[unknown]` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + 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 item. One of `in_progress`, `completed`, or - `incomplete`. Populated when 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) - - `Program object { id, call_id, code, 3 more }` + - `name: string` - - `id: string` + The name of the custom tool, used to identify it in tool calls. - The unique ID of the program item. + - `type: "custom"` - - `call_id: string` + The type of the custom tool. Always `custom`. - The stable call ID of the program item. + - `"custom"` - - `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"` + - `defer_loading: optional boolean` - The type of the item. Always `program`. + Whether this tool should be deferred and discovered via tool search. - - `"program"` + - `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 }` - - `ProgramOutput object { id, call_id, result, 3 more }` + Unconstrained free-form text. - - `id: string` + - `type: "text"` - The unique ID of the program output item. + Unconstrained text format. Always `text`. - - `call_id: string` + - `"text"` - The call ID of the program item. + - `Grammar object { definition, syntax, type }` - - `result: string` + A grammar defined by the user. - The result produced by the program item. + - `definition: string` - - `status: "completed" or "incomplete"` + The grammar definition. - The terminal status of the program output item. + - `syntax: "lark" or "regex"` - - `"completed"` + The syntax of the grammar definition. One of `lark` or `regex`. - - `"incomplete"` + - `"lark"` - - `type: "program_output"` + - `"regex"` - The type of the item. Always `program_output`. + - `type: "grammar"` - - `"program_output"` + 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"` - - `ToolSearchCall object { id, arguments, call_id, 5 more }` + - `ToolSearch object { type, description, execution, parameters }` - - `id: string` + Hosted or BYOT tool search configuration for deferred tools. - The unique ID of the tool search call item. + - `type: "tool_search"` - - `arguments: unknown` + The type of the tool. Always `tool_search`. - Arguments used for the tool search call. + - `"tool_search"` - - `call_id: string` + - `description: optional string` - The unique ID of the tool search call generated by the model. + Description shown to the model for a client-executed tool search tool. - - `execution: "server" or "client"` + - `execution: optional "server" or "client"` - Whether tool search was executed by the server or by the client. + Whether tool search is 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. + - `parameters: optional unknown` - - `"in_progress"` + Parameter schema for a client-executed tool search tool. - - `"completed"` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - - `"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). - - `type: "tool_search_call"` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - The type of the item. Always `tool_search_call`. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `"tool_search_call"` + - `"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"` - - `created_by: optional string` + - `search_context_size: optional "low" or "medium" or "high"` - The identifier of the actor that created the item. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `ToolSearchOutput object { id, call_id, execution, 5 more }` + - `"low"` - - `id: string` + - `"medium"` - The unique ID of the tool search output item. + - `"high"` - - `call_id: string` + - `user_location: optional object { type, city, country, 2 more }` - The unique ID of the tool search call generated by the model. + The user's location. - - `execution: "server" or "client"` + - `type: "approximate"` - Whether tool search was executed by the server or by the client. + The type of location approximation. Always `approximate`. - - `"server"` + - `"approximate"` - - `"client"` + - `city: optional string` - - `status: "in_progress" or "completed" or "incomplete"` + Free text input for the city of the user, e.g. `San Francisco`. - The status of the tool search output item that was recorded. + - `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`. - - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` + - `timezone: optional string` - The loaded tool definitions returned by tool search. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `Function object { name, parameters, strict, 5 more }` + - `ApplyPatch object { type, allowed_callers }` - 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). + Allows the assistant to create, delete, or update files using unified diffs. - - `name: string` + - `type: "apply_patch"` - The name of the function to call. + The type of the tool. Always `apply_patch`. - - `parameters: map[unknown]` + - `"apply_patch"` - A JSON schema object describing the parameters of the function. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `strict: boolean` + The tool invocation context(s). - Whether strict parameter validation is enforced for this function tool. + - `"direct"` - - `type: "function"` + - `"programmatic"` - The type of the function tool. Always `function`. + - `type: "additional_tools"` - - `"function"` + The type of the item. Always `additional_tools`. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"additional_tools"` - 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. + - `Compaction object { id, encrypted_content, type, 2 more }` - - `description: optional string` + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). - 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 compaction item. - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `encrypted_content: string` - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + The encrypted content that was produced by 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). + - `type: "compaction"` - - `type: "file_search"` + The type of the item. Always `compaction`. - The type of the file search tool. Always `file_search`. + - `"compaction"` - - `"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. + - `created_by: optional string` - - `ComparisonFilter object { key, type, value }` + The identifier of the actor that created the item. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `ImageGenerationCall object { id, result, status, 2 more }` - - `key: string` + An image generation request made by the model. - The key to compare against the value. + - `id: string` - - `type: "eq" or "ne" or "gt" or 5 more` + The unique ID of the image generation call. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `result: 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 generated image encoded in base64. - - `"eq"` + - `status: "in_progress" or "completed" or "generating" or "failed"` - - `"ne"` + The status of the image generation call. - - `"gt"` + - `"in_progress"` - - `"gte"` + - `"completed"` - - `"lt"` + - `"generating"` - - `"lte"` + - `"failed"` - - `"in"` + - `type: "image_generation_call"` - - `"nin"` + The type of the image generation call. Always `image_generation_call`. - - `value: string or number or boolean or array of string or number` + - `"image_generation_call"` - The value to compare against the attribute key; supports string, number, or boolean types. + - `agent: optional object { agent_name }` - - `string` + The agent that produced this item. - - `number` + - `agent_name: string` - - `boolean` + The canonical name of the agent that produced this item. - - `array of string or number` + - `CodeInterpreterCall object { id, code, container_id, 4 more }` - - `string` + A tool call to run code. - - `number` + - `id: string` - - `CompoundFilter object { filters, type }` + The unique ID of the code interpreter tool call. - Combine multiple filters using `and` or `or`. + - `code: string` - - `filters: array of object { key, type, value } or unknown` + The code to run, or null if not available. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `container_id: string` - - `ComparisonFilter object { key, type, value }` + The ID of the container used to run the code. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `outputs: array of object { logs, type } or object { type, url }` - - `key: string` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - The key to compare against the value. + - `Logs object { logs, type }` - - `type: "eq" or "ne" or "gt" or 5 more` + The logs output from the code interpreter. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `logs: 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 logs output from the code interpreter. - - `"eq"` + - `type: "logs"` - - `"ne"` + The type of the output. Always `logs`. - - `"gt"` + - `"logs"` - - `"gte"` + - `Image object { type, url }` - - `"lt"` + The image output from the code interpreter. - - `"lte"` + - `type: "image"` - - `"in"` + The type of the output. Always `image`. - - `"nin"` + - `"image"` - - `value: string or number or boolean or array of string or number` + - `url: string` - The value to compare against the attribute key; supports string, number, or boolean types. + The URL of the image output from the code interpreter. - - `string` + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - - `number` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `boolean` + - `"in_progress"` - - `array of string or number` + - `"completed"` - - `string` + - `"incomplete"` - - `number` + - `"interpreting"` - - `unknown` + - `"failed"` - - `type: "and" or "or"` + - `type: "code_interpreter_call"` - Type of operation: `and` or `or`. + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `"and"` + - `"code_interpreter_call"` - - `"or"` + - `agent: optional object { agent_name }` - - `max_num_results: optional number` + The agent that produced this item. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `agent_name: string` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + The canonical name of the agent that produced this item. - Ranking options for search. + - `LocalShellCall object { id, action, call_id, 3 more }` - - `hybrid_search: optional object { embedding_weight, text_weight }` + A tool call to run a command on the local shell. - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `id: string` - - `embedding_weight: number` + The unique ID of the local shell call. - The weight of the embedding in the reciprocal ranking fusion. + - `action: object { command, env, type, 3 more }` - - `text_weight: number` + Execute a shell command on the server. - The weight of the text in the reciprocal ranking fusion. + - `command: array of string` - - `ranker: optional "auto" or "default-2024-11-15"` + The command to run. - The ranker to use for the file search. + - `env: map[string]` - - `"auto"` + Environment variables to set for the command. - - `"default-2024-11-15"` + - `type: "exec"` - - `score_threshold: optional number` + The type of the local shell action. Always `exec`. - 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. + - `"exec"` - - `Computer object { type }` + - `timeout_ms: optional number` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + Optional timeout in milliseconds for the command. - - `type: "computer"` + - `user: optional string` - The type of the computer tool. Always `computer`. + Optional user to run the command as. - - `"computer"` + - `working_directory: optional string` - - `ComputerUsePreview object { display_height, display_width, environment, type }` + Optional working directory to run the command in. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `call_id: string` - - `display_height: number` + The unique ID of the local shell tool call generated by the model. - The height of the computer display. + - `status: "in_progress" or "completed" or "incomplete"` - - `display_width: number` + The status of the local shell call. - 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"` + - `type: "local_shell_call"` - - `"mac"` + The type of the local shell call. Always `local_shell_call`. - - `"linux"` + - `"local_shell_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"` + - `LocalShellCallOutput object { id, output, type, 2 more }` - - `WebSearch object { type, filters, search_context_size, user_location }` + The output of a local shell tool call. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `id: string` - - `type: "web_search" or "web_search_2025_08_26"` + The unique ID of the local shell tool call generated by the model. - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `output: string` - - `"web_search"` + A JSON string of the output of the local shell tool call. - - `"web_search_2025_08_26"` + - `type: "local_shell_call_output"` - - `filters: optional object { allowed_domains }` + The type of the local shell tool call output. Always `local_shell_call_output`. - Filters for the search. + - `"local_shell_call_output"` - - `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 item. One of `in_progress`, `completed`, or `incomplete`. - - `"medium"` + - `"in_progress"` - - `"high"` + - `"completed"` - - `user_location: optional object { city, country, region, 2 more }` + - `"incomplete"` - The approximate location of the user. + - `ShellCall object { id, action, call_id, 6 more }` - - `city: optional string` + A tool call that executes one or more shell commands in a managed environment. - Free text input for the city of the user, e.g. `San Francisco`. + - `id: string` - - `country: optional string` + The unique ID of the shell tool call. Populated when this item is returned via API. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `action: object { commands, max_output_length, timeout_ms }` - - `region: optional string` + The shell commands and limits that describe how to run the tool call. - Free text input for the region of the user, e.g. `California`. + - `commands: array of string` - - `timezone: optional string` + - `max_output_length: number` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + Optional maximum number of characters to return from each command. - - `type: optional "approximate"` + - `timeout_ms: number` - The type of location approximation. Always `approximate`. + Optional timeout in milliseconds for the commands. - - `"approximate"` + - `call_id: string` - - `Mcp object { server_label, type, allowed_callers, 9 more }` + The unique ID of the shell tool call generated by the model. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` - - `server_label: string` + Represents the use of a local environment to perform shell actions. - A label for this MCP server, used to identify it in tool calls. + - `BetaResponseLocalEnvironment object { type }` - - `type: "mcp"` + Represents the use of a local environment to perform shell actions. - The type of the MCP tool. Always `mcp`. + - `type: "local"` - - `"mcp"` + The environment type. Always `local`. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"local"` - The tool invocation context(s). + - `BetaResponseContainerReference object { container_id, type }` - - `"direct"` + Represents a container created with /v1/containers. - - `"programmatic"` + - `container_id: string` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + - `type: "container_reference"` - List of allowed tool names or a filter object. + The environment type. Always `container_reference`. - - `McpAllowedTools = array of string` + - `"container_reference"` - A string array of allowed tool names + - `status: "in_progress" or "completed" or "incomplete"` - - `McpToolFilter object { read_only, tool_names }` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - A filter object to specify which tools are allowed. + - `"in_progress"` - - `read_only: optional boolean` + - `"completed"` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `"incomplete"` - - `tool_names: optional array of string` + - `type: "shell_call"` - List of allowed tool names. + The type of the item. Always `shell_call`. - - `authorization: optional string` + - `"shell_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. + - `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](https://platform.openai.com/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"` + - `"direct"` - - `"connector_microsoftteams"` + - `Program object { caller_id, type }` - - `"connector_outlookcalendar"` + - `caller_id: string` - - `"connector_outlookemail"` + The call ID of the program item that produced this tool call. - - `"connector_sharepoint"` + - `type: "program"` - - `defer_loading: optional boolean` + - `"program"` - Whether this MCP tool is deferred and discovered via tool search. + - `created_by: optional string` - - `headers: optional map[string]` + The ID of the entity that created this tool call. - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `ShellCallOutput object { id, call_id, max_output_length, 6 more }` - - `require_approval: optional object { always, never } or "always" or "never"` + The output of a shell tool call that was emitted. - Specify which of the MCP server's tools require approval. + - `id: string` - - `McpToolApprovalFilter object { always, never }` + The unique ID of the shell call output. Populated when this item is returned via API. - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `call_id: string` - - `always: optional object { read_only, tool_names }` + The unique ID of the 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 }` - - `never: optional 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"` - - `McpToolApprovalSetting = "always" or "never"` + - `Exit object { exit_code, 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. + Indicates that the shell commands finished and returned an exit code. - - `"always"` + - `exit_code: number` - - `"never"` + Exit code from the shell process. - - `server_description: optional string` + - `type: "exit"` - Optional description of the MCP server, used to provide more context. + The outcome type. Always `exit`. - - `server_url: optional string` + - `"exit"` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `stderr: string` - - `tunnel_id: optional string` + The standard error output that was captured. - 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. + - `stdout: string` - - `CodeInterpreter object { container, type, allowed_callers }` + The standard output that was captured. - A tool that runs Python code to help generate a response to a prompt. + - `created_by: optional string` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + The identifier of the actor that created the item. - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + - `status: "in_progress" or "completed" or "incomplete"` - - `string` + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - The container ID. + - `"in_progress"` - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + - `"completed"` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `"incomplete"` - - `type: "auto"` + - `type: "shell_call_output"` - Always `auto`. + The type of the shell call output. Always `shell_call_output`. - - `"auto"` + - `"shell_call_output"` - - `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` + - `"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"` + - `"program"` - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `created_by: optional string` - - `allowed_domains: array of string` + The identifier of the actor that created the item. - A list of allowed domains when type is `allowlist`. + - `ApplyPatchCall object { id, call_id, operation, 5 more }` - - `type: "allowlist"` + A tool call that applies file diffs by creating, deleting, or updating files. - Allow outbound network access only to specified domains. Always `allowlist`. + - `id: string` - - `"allowlist"` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` + - `call_id: string` - Optional domain-scoped secrets for allowlisted domains. + The unique ID of the apply patch tool call generated by the model. - - `domain: string` + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - The domain associated with the secret. + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `name: string` + - `CreateFile object { diff, path, type }` - The name of the secret to inject for the domain. + Instruction describing how to create a file via the apply_patch tool. - - `value: string` + - `diff: string` - The secret value to inject for the domain. + Diff to apply. - - `type: "code_interpreter"` + - `path: string` - The type of the code interpreter tool. Always `code_interpreter`. + Path of the file to create. - - `"code_interpreter"` + - `type: "create_file"` - - `allowed_callers: optional array of "direct" or "programmatic"` + Create a new file with the provided diff. - The tool invocation context(s). + - `"create_file"` - - `"direct"` + - `DeleteFile object { path, type }` - - `"programmatic"` + Instruction describing how to delete a file via the apply_patch tool. - - `ProgrammaticToolCalling object { type }` + - `path: string` - - `type: "programmatic_tool_calling"` + Path of the file to delete. - The type of the tool. Always `programmatic_tool_calling`. + - `type: "delete_file"` - - `"programmatic_tool_calling"` + Delete the specified file. - - `ImageGeneration object { type, action, background, 9 more }` + - `"delete_file"` - A tool that generates images using the GPT image models. + - `UpdateFile object { diff, path, type }` - - `type: "image_generation"` + Instruction describing how to update a file via the apply_patch tool. - The type of the image generation tool. Always `image_generation`. + - `diff: string` - - `"image_generation"` + Diff to apply. - - `action: optional "generate" or "edit" or "auto"` + - `path: string` - Whether to generate a new image or edit an existing image. Default: `auto`. + Path of the file to update. - - `"generate"` + - `type: "update_file"` - - `"edit"` + Update an existing file with the provided diff. - - `"auto"` + - `"update_file"` - - `background: optional "transparent" or "opaque" or "auto"` + - `status: "in_progress" or "completed"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + The status of the apply patch tool call. One of `in_progress` or `completed`. - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + - `"in_progress"` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `"completed"` - - `"transparent"` + - `type: "apply_patch_call"` - - `"opaque"` + The type of the item. Always `apply_patch_call`. - - `"auto"` + - `"apply_patch_call"` - - `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` + - `"direct"` - Base64-encoded mask image. + - `Program object { caller_id, type }` - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `caller_id: string` - The image generation model to use. Default: `gpt-image-1`. + The call ID of the program item that produced this tool call. - - `string` + - `type: "program"` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `"program"` - The image generation model to use. Default: `gpt-image-1`. + - `created_by: optional string` - - `"gpt-image-1"` + The ID of the entity that created this tool call. - - `"gpt-image-1-mini"` + - `ApplyPatchCallOutput object { id, call_id, status, 5 more }` - - `"gpt-image-2"` + The output emitted by an apply patch tool call. - - `"gpt-image-2-2026-04-21"` + - `id: string` - - `"gpt-image-1.5"` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `"chatgpt-image-latest"` + - `call_id: string` - - `moderation: optional "auto" or "low"` + The unique ID of the apply patch tool call generated by the model. - Moderation level for the generated image. Default: `auto`. + - `status: "completed" or "failed"` - - `"auto"` + The status of the apply patch tool call output. One of `completed` or `failed`. - - `"low"` + - `"completed"` - - `output_compression: optional number` + - `"failed"` - Compression level for the output image. Default: 100. + - `type: "apply_patch_call_output"` - - `output_format: optional "png" or "webp" or "jpeg"` + The type of the item. Always `apply_patch_call_output`. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `"apply_patch_call_output"` - - `"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"` + - `created_by: optional string` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + The ID of the entity that created this tool call output. - - `"1024x1024"` + - `output: optional string` - - `"1024x1536"` + Optional textual output returned by the apply patch tool. - - `"1536x1024"` + - `McpCall object { id, arguments, name, 7 more }` - - `"auto"` + An invocation of a tool on an MCP server. - - `LocalShell object { type }` + - `id: string` - A tool that allows the model to execute shell commands in a local environment. + The unique ID of the tool call. - - `type: "local_shell"` + - `arguments: string` - The type of the local shell tool. Always `local_shell`. + A JSON string of the arguments passed to the tool. - - `"local_shell"` + - `name: string` - - `Shell object { type, allowed_callers, environment }` + The name of the tool that was run. - A tool that allows the model to execute shell commands. + - `server_label: string` - - `type: "shell"` + The label of the MCP server running the tool. - The type of the shell tool. Always `shell`. + - `type: "mcp_call"` - - `"shell"` + The type of the item. Always `mcp_call`. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"mcp_call"` - 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 }` + - `approval_request_id: optional string` - - `type: "container_auto"` + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - Automatically creates a container for this request + - `error: optional string` - - `"container_auto"` + The error from the tool call, if any. - - `file_ids: optional array of string` + - `output: optional string` - An optional list of uploaded files to make available to your code. + The output from the tool call. - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - The memory limit for the container. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `"1g"` + - `"in_progress"` - - `"4g"` + - `"completed"` - - `"16g"` + - `"incomplete"` - - `"64g"` + - `"calling"` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `"failed"` - Network access policy for the container. + - `McpListTools object { id, server_label, tools, 3 more }` - - `BetaContainerNetworkPolicyDisabled object { type }` + A list of tools available on an MCP server. - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `id: string` - - `skills: optional array of BetaSkillReference or BetaInlineSkill` + The unique ID of the list. - An optional list of skills referenced by id or inline data. + - `server_label: string` - - `BetaSkillReference object { skill_id, type, version }` + The label of the MCP server. - - `skill_id: string` + - `tools: array of object { input_schema, name, annotations, description }` - The ID of the referenced skill. + The tools available on the server. - - `type: "skill_reference"` + - `input_schema: unknown` - References a skill created with the /v1/skills endpoint. + The JSON schema describing the tool's input. - - `"skill_reference"` + - `name: string` - - `version: optional string` + The name of the tool. - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `annotations: optional unknown` - - `BetaInlineSkill object { description, name, source, type }` + Additional annotations about the tool. - - `description: string` + - `description: optional string` - The description of the skill. + The description of the tool. - - `name: string` + - `type: "mcp_list_tools"` - The name of the skill. + The type of the item. Always `mcp_list_tools`. - - `source: BetaInlineSkillSource` + - `"mcp_list_tools"` - Inline skill payload + - `agent: optional object { agent_name }` - - `data: string` + The agent that produced this item. - Base64-encoded skill zip bundle. + - `agent_name: string` - - `media_type: "application/zip"` + The canonical name of the agent that produced this item. - The media type of the inline skill payload. Must be `application/zip`. + - `error: optional string` - - `"application/zip"` + Error message if the server could not list tools. - - `type: "base64"` + - `McpApprovalRequest object { id, arguments, name, 3 more }` - The type of the inline skill source. Must be `base64`. + A request for human approval of a tool invocation. - - `"base64"` + - `id: string` - - `type: "inline"` + The unique ID of the approval request. - Defines an inline skill for this request. + - `arguments: string` - - `"inline"` + A JSON string of arguments for the tool. - - `BetaLocalEnvironment object { type, skills }` + - `name: string` - - `type: "local"` + The name of the tool to run. - Use a local computer environment. + - `server_label: string` - - `"local"` + The label of the MCP server making the request. - - `skills: optional array of BetaLocalSkill` + - `type: "mcp_approval_request"` - An optional list of skills. + The type of the item. Always `mcp_approval_request`. - - `description: string` + - `"mcp_approval_request"` - The description of the skill. + - `agent: optional object { agent_name }` - - `name: string` + The agent that produced this item. - The name of the skill. + - `agent_name: string` - - `path: string` + The canonical name of the agent that produced this item. - The path to the directory containing the skill. + - `McpApprovalResponse object { id, approval_request_id, approve, 3 more }` - - `BetaContainerReference object { container_id, type }` + A response to an MCP approval request. - - `container_id: string` + - `id: string` - The ID of the referenced container. + The unique ID of the approval response - - `type: "container_reference"` + - `approval_request_id: string` - References a container created with the /v1/containers endpoint + The ID of the approval request being answered. - - `"container_reference"` + - `approve: boolean` - - `Custom object { name, type, allowed_callers, 3 more }` + Whether the request was approved. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `type: "mcp_approval_response"` - - `name: string` + The type of the item. Always `mcp_approval_response`. - The name of the custom tool, used to identify it in tool calls. + - `"mcp_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"` + - `CustomToolCall object { call_id, input, name, 5 more }` - - `defer_loading: optional boolean` + A call to a custom tool created by the model. - Whether this tool should be deferred and discovered via tool search. + - `call_id: string` - - `description: optional string` + An identifier used to map this custom tool call to a tool call output. - Optional description of the custom tool, used to provide more context. + - `input: string` - - `format: optional object { type } or object { definition, syntax, type }` + The input for the custom tool call generated by the model. - The input format for the custom tool. Default is unconstrained text. + - `name: string` - - `Text object { type }` + The name of the custom tool being called. - Unconstrained free-form text. + - `type: "custom_tool_call"` - - `type: "text"` + The type of the custom tool call. Always `custom_tool_call`. - Unconstrained text format. Always `text`. + - `"custom_tool_call"` - - `"text"` + - `id: optional string` - - `Grammar object { definition, syntax, type }` + The unique ID of the custom tool call in the OpenAI platform. - 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 }` - - `Namespace object { description, name, tools, type }` + - `caller_id: string` - Groups function/custom tools under a shared namespace. + The call ID of the program item that produced this tool call. - - `description: string` + - `type: "program"` - A description of the namespace shown to the model. + - `"program"` - - `name: string` + - `namespace: optional string` - The namespace name used in tool calls (for example, `crm`). + The namespace of the custom tool being called. - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + - `CustomToolCallOutput object { id, call_id, output, 5 more }` - The function/custom tools available inside this namespace. + - `id: string` - - `Function object { name, type, allowed_callers, 5 more }` + The unique ID of the custom tool call output item. - - `name: string` + - `call_id: string` - - `type: "function"` + The call ID, used to map this custom tool call output to a custom tool call. - - `"function"` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `allowed_callers: optional array of "direct" or "programmatic"` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - The tool invocation context(s). + - `StringOutput = string` - - `"direct"` + A string of the output of the custom tool call. - - `"programmatic"` + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `defer_loading: optional boolean` + Text, image, or file output of the custom tool call. - Whether this function should be deferred and discovered via tool search. + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `description: optional string` + A text input to the model. - - `output_schema: optional map[unknown]` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `parameters: optional unknown` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `strict: optional boolean` + A file input to the model. - 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. + - `status: "in_progress" or "completed" or "incomplete"` - - `Custom object { name, type, allowed_callers, 3 more }` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `"in_progress"` - - `name: string` + - `"completed"` - The name of the custom tool, used to identify it in tool calls. + - `"incomplete"` - - `type: "custom"` + - `type: "custom_tool_call_output"` - The type of the custom tool. Always `custom`. + The type of the custom tool call output. Always `custom_tool_call_output`. - - `"custom"` + - `"custom_tool_call_output"` - - `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 }` + The caller type. Always `direct`. - The input format for the custom tool. Default is unconstrained text. + - `"direct"` - - `Text object { type }` + - `Program object { caller_id, type }` - Unconstrained free-form text. + - `caller_id: string` - - `type: "text"` + The call ID of the program item that produced this tool call. - Unconstrained text format. Always `text`. + - `type: "program"` - - `"text"` + The caller type. Always `program`. - - `Grammar object { definition, syntax, type }` + - `"program"` - A grammar defined by the user. + - `created_by: optional string` - - `definition: string` + The identifier of the actor that created the item. - The grammar definition. + - `parallel_tool_calls: boolean` - - `syntax: "lark" or "regex"` + Whether to allow the model to run tool calls in parallel. - The syntax of the grammar definition. One of `lark` or `regex`. + - `temperature: number` - - `"lark"` + 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. - - `"regex"` + - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` - - `type: "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. - 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: 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` + We support the following categories of tools: - The additional tool definitions 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 }` @@ -157577,7 +156694,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-web-search). + [web search tool](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -157637,7 +156754,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -157689,7 +156806,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -157881,19 +156998,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `background: optional "transparent" or "opaque" or "auto"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. - - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. - - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - `"transparent"` @@ -157922,13 +157028,13 @@ curl -X POST https://api.openai.com/v1/responses/compact \ Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `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-2" or 3 more` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` The image generation model to use. Default: `gpt-image-1`. @@ -157936,14 +157042,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"gpt-image-1-mini"` - - `"gpt-image-2"` - - - `"gpt-image-2-2026-04-21"` - - `"gpt-image-1.5"` - - `"chatgpt-image-latest"` - - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -158040,7 +157140,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -158154,7 +157254,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -158322,1005 +157422,1479 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"programmatic"` - - `type: "additional_tools"` + - `top_p: number` - The type of the item. Always `additional_tools`. + An alternative to sampling with temperature, called nucleus sampling, + where the model considers the results of the tokens with top_p probability + mass. So 0.1 means only the tokens comprising the top 10% probability mass + are considered. - - `"additional_tools"` + We generally recommend altering this or `temperature` but not both. - - `agent: optional object { agent_name }` + - `background: optional boolean` - The agent that produced this item. + Whether to run the model response in the background. + [Learn more](/docs/guides/background). - - `agent_name: string` + - `completed_at: optional number` - The canonical name of the agent that produced this item. + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - - `Compaction object { id, encrypted_content, type, 2 more }` + - `conversation: optional object { id }` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + 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 compaction item. + The unique ID of the conversation that this response was associated with. - - `encrypted_content: string` + - `max_output_tokens: optional number` - The encrypted content that was produced by compaction. + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](/docs/guides/reasoning). - - `type: "compaction"` + - `max_tool_calls: optional number` - The type of the item. Always `compaction`. + 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. - - `"compaction"` + - `moderation: optional object { input, output }` - - `agent: optional object { agent_name }` + Moderation results for the response input and output, if moderated completions were requested. - The agent that produced this item. + - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` - - `agent_name: string` + Moderation for the response input. - The canonical name of the agent that produced this item. + - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` - - `created_by: optional string` + A moderation result produced for the response input or output. - The identifier of the actor that created the item. + - `categories: map[boolean]` - - `ImageGenerationCall object { id, result, status, 2 more }` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - An image generation request made by the model. + - `category_applied_input_types: map[array of "text" or "image"]` - - `id: string` + Which modalities of input are reflected by the score for each category. - The unique ID of the image generation call. + - `"text"` - - `result: string` + - `"image"` - The generated image encoded in base64. + - `category_scores: map[number]` - - `status: "in_progress" or "completed" or "generating" or "failed"` + A dictionary of moderation categories to scores. - The status of the image generation call. + - `flagged: boolean` - - `"in_progress"` + A boolean indicating whether the content was flagged by any category. - - `"completed"` + - `model: string` - - `"generating"` + The moderation model that produced this result. - - `"failed"` + - `type: "moderation_result"` - - `type: "image_generation_call"` + The object type, which was always `moderation_result` for successful moderation results. - The type of the image generation call. Always `image_generation_call`. + - `"moderation_result"` - - `"image_generation_call"` + - `Error object { code, message, type }` - - `agent: optional object { agent_name }` + An error produced while attempting moderation for the response input or output. - The agent that produced this item. + - `code: string` - - `agent_name: string` + The error code. - The canonical name of the agent that produced this item. + - `message: string` - - `CodeInterpreterCall object { id, code, container_id, 4 more }` + The error message. - A tool call to run code. + - `type: "error"` - - `id: string` + The object type, which was always `error` for moderation failures. - The unique ID of the code interpreter tool call. + - `"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 code to run, or null if not available. + The error code. - - `container_id: string` + - `message: string` - The ID of the container used to run the code. + The error message. - - `outputs: array of object { logs, type } or object { type, url }` + - `type: "error"` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + The object type, which was always `error` for moderation failures. - - `Logs object { logs, type }` + - `"error"` - The logs output from the code interpreter. + - `output_text: optional string` - - `logs: 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 logs output from the code interpreter. + - `previous_response_id: optional string` - - `type: "logs"` + The unique ID of the previous response to the model. Use this to + create multi-turn conversations. Learn more about + [conversation state](/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. - The type of the output. Always `logs`. + - `prompt: optional BetaResponsePrompt` - - `"logs"` + Reference to a prompt template and its variables. + [Learn more](/docs/guides/text?api-mode=responses#reusable-prompts). - - `Image object { type, url }` + - `id: string` - The image output from the code interpreter. + The unique identifier of the prompt template to use. - - `type: "image"` + - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` - The type of the output. Always `image`. + 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. - - `"image"` + - `string` - - `url: string` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - The URL of the image output from the code interpreter. + A text input to the model. - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `"in_progress"` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `"completed"` + A file input to the model. - - `"incomplete"` + - `version: optional string` - - `"interpreting"` + Optional version of the prompt template. - - `"failed"` + - `prompt_cache_key: optional string` - - `type: "code_interpreter_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). - The type of the code interpreter tool call. Always `code_interpreter_call`. + - `prompt_cache_options: optional object { mode, ttl }` - - `"code_interpreter_call"` + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - - `agent: optional object { agent_name }` + - `mode: "implicit" or "explicit"` - The agent that produced this item. + Whether implicit prompt-cache breakpoints were enabled. - - `agent_name: string` + - `"implicit"` - The canonical name of the agent that produced this item. + - `"explicit"` - - `LocalShellCall object { id, action, call_id, 3 more }` + - `ttl: "30m"` - A tool call to run a command on the local shell. + The minimum lifetime applied to each cache breakpoint. - - `id: string` + - `"30m"` - The unique ID of the local shell call. + - `prompt_cache_retention: optional "in_memory" or "24h"` - - `action: object { command, env, type, 3 more }` + Deprecated. Use `prompt_cache_options.ttl` instead. - Execute a shell command on the server. + 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. - - `command: array of string` + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - The command to run. + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - - `env: map[string]` + - `"in_memory"` - Environment variables to set for the command. + - `"24h"` - - `type: "exec"` + - `reasoning: optional object { context, effort, generate_summary, 2 more }` - The type of the local shell action. Always `exec`. + **gpt-5 and o-series models only** - - `"exec"` + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - `timeout_ms: optional number` + - `context: optional "auto" or "current_turn" or "all_turns"` - Optional timeout in milliseconds for the command. + Controls which reasoning items are rendered back to the model on later turns. + When returned on a response, this is the effective reasoning context mode + used for the response. - - `user: optional string` + - `"auto"` - Optional user to run the command as. + - `"current_turn"` - - `working_directory: optional string` + - `"all_turns"` - Optional working directory to run the command in. + - `effort: optional "none" or "minimal" or "low" or 4 more` - - `call_id: 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 local shell tool call generated by the model. + - `"none"` - - `status: "in_progress" or "completed" or "incomplete"` + - `"minimal"` - The status of the local shell call. + - `"low"` - - `"in_progress"` + - `"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"` - - `type: "local_shell_call"` + - `text: optional BetaResponseTextConfig` - The type of the local shell call. Always `local_shell_call`. + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - - `"local_shell_call"` + - [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`. + + - `"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 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. - - `LocalShellCallOutput object { id, output, type, 2 more }` +### Beta Response Reasoning Summary Part Added Event - The output of a local shell tool call. +- `BetaResponseReasoningSummaryPartAddedEvent object { item_id, output_index, part, 4 more }` - - `id: string` + Emitted when a new reasoning summary part is added. - The unique ID of the local shell tool call generated by the model. + - `item_id: string` - - `output: string` + The ID of the item this summary part is associated with. - A JSON string of the output of the local shell tool call. + - `output_index: number` - - `type: "local_shell_call_output"` + The index of the output item this summary part is associated with. - The type of the local shell tool call output. Always `local_shell_call_output`. + - `part: object { text, type }` - - `"local_shell_call_output"` + 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 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"` +### Beta Response Reasoning Summary Part Done Event - The status of the item. One of `in_progress`, `completed`, or `incomplete`. +- `BetaResponseReasoningSummaryPartDoneEvent object { item_id, output_index, part, 5 more }` - - `"in_progress"` + Emitted when a reasoning summary part is completed. - - `"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 }` + + The completed summary part. + + - `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.done"` + + The type of the event. Always `response.reasoning_summary_part.done`. + + - `"response.reasoning_summary_part.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. + + - `status: optional "incomplete"` + + The completion status of the summary part. Omitted when the part completed + normally and set to `incomplete` when generation was interrupted. - `"incomplete"` - - `ShellCall object { id, action, call_id, 6 more }` +### Beta Response Reasoning Summary Text Delta Event - A tool call that executes one or more shell commands in a managed environment. +- `BetaResponseReasoningSummaryTextDeltaEvent object { delta, item_id, output_index, 4 more }` - - `id: string` + Emitted when a delta is added to a reasoning summary text. - 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 }` + The text delta that was added to the summary. - The shell commands and limits that describe how to run the tool call. + - `item_id: string` - - `commands: array of string` + The ID of the item this summary text delta is associated with. - - `max_output_length: number` + - `output_index: number` - Optional maximum number of characters to return from each command. + The index of the output item this summary text delta is associated with. - - `timeout_ms: number` + - `sequence_number: number` - Optional timeout in milliseconds for the commands. + The sequence number of this event. - - `call_id: string` + - `summary_index: number` - The unique ID of the shell tool call generated by the model. + The index of the summary part within the reasoning summary. - - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` + - `type: "response.reasoning_summary_text.delta"` - Represents the use of a local environment to perform shell actions. + The type of the event. Always `response.reasoning_summary_text.delta`. - - `BetaResponseLocalEnvironment object { type }` + - `"response.reasoning_summary_text.delta"` - Represents the use of a local environment to perform shell actions. + - `agent: optional object { agent_name }` - - `type: "local"` + The agent that owns this multi-agent streaming event. - The environment type. Always `local`. + - `agent_name: string` - - `"local"` + The canonical name of the agent that produced this item. - - `BetaResponseContainerReference object { container_id, type }` +### Beta Response Reasoning Summary Text Done Event - Represents a container created with /v1/containers. +- `BetaResponseReasoningSummaryTextDoneEvent object { item_id, output_index, sequence_number, 4 more }` - - `container_id: string` + Emitted when a reasoning summary text is completed. - - `type: "container_reference"` + - `item_id: string` - The environment type. Always `container_reference`. + The ID of the item this summary text is associated with. - - `"container_reference"` + - `output_index: number` - - `status: "in_progress" or "completed" or "incomplete"` + The index of the output item this summary text is associated with. - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `sequence_number: number` - - `"in_progress"` + The sequence number of this event. - - `"completed"` + - `summary_index: number` - - `"incomplete"` + The index of the summary part within the reasoning summary. - - `type: "shell_call"` + - `text: string` - The type of the item. Always `shell_call`. + The full text of the completed reasoning summary. - - `"shell_call"` + - `type: "response.reasoning_summary_text.done"` + + The type of the event. Always `response.reasoning_summary_text.done`. + + - `"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. - - `caller: optional object { type } or object { caller_id, type }` +### Beta Response Reasoning Text Delta Event - The execution context that produced this tool call. +- `BetaResponseReasoningTextDeltaEvent object { content_index, delta, item_id, 4 more }` - - `Direct object { type }` + Emitted when a delta is added to a reasoning text. - - `type: "direct"` + - `content_index: number` - - `"direct"` + The index of the reasoning content part this delta is associated with. - - `Program object { caller_id, type }` + - `delta: string` - - `caller_id: string` + The text delta that was added to the reasoning content. - The call ID of the program item that produced this tool call. + - `item_id: string` - - `type: "program"` + The ID of the item this reasoning text delta is associated with. - - `"program"` + - `output_index: number` - - `created_by: optional string` + The index of the output item this reasoning text delta is associated with. - The ID of the entity that created this tool call. + - `sequence_number: number` - - `ShellCallOutput object { id, call_id, max_output_length, 6 more }` + The sequence number of this event. - The output of a shell tool call that was emitted. + - `type: "response.reasoning_text.delta"` - - `id: string` + The type of the event. Always `response.reasoning_text.delta`. - The unique ID of the shell call output. Populated when this item is returned via API. + - `"response.reasoning_text.delta"` - - `call_id: string` + - `agent: optional object { agent_name }` - The unique ID of the shell tool call generated by the model. + The agent that owns this multi-agent streaming event. - - `max_output_length: number` + - `agent_name: 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 canonical name of the agent that produced this item. - - `output: array of object { outcome, stderr, stdout, created_by }` +### Beta Response Reasoning Text Done Event - An array of shell call output contents +- `BetaResponseReasoningTextDoneEvent object { content_index, item_id, output_index, 4 more }` - - `outcome: object { type } or object { exit_code, type }` + Emitted when a reasoning text is completed. - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + - `content_index: number` - - `Timeout object { type }` + The index of the reasoning content part. - Indicates that the shell call exceeded its configured time limit. + - `item_id: string` - - `type: "timeout"` + The ID of the item this reasoning text is associated with. - The outcome type. Always `timeout`. + - `output_index: number` - - `"timeout"` + The index of the output item this reasoning text is associated with. - - `Exit object { exit_code, type }` + - `sequence_number: number` - Indicates that the shell commands finished and returned an exit code. + The sequence number of this event. - - `exit_code: number` + - `text: string` - Exit code from the shell process. + The full text of the completed reasoning content. - - `type: "exit"` + - `type: "response.reasoning_text.done"` - The outcome type. Always `exit`. + The type of the event. Always `response.reasoning_text.done`. - - `"exit"` + - `"response.reasoning_text.done"` - - `stderr: string` + - `agent: optional object { agent_name }` - The standard error output that was captured. + The agent that owns this multi-agent streaming event. - - `stdout: string` + - `agent_name: string` - The standard output that was captured. + The canonical name of the agent that produced this item. - - `created_by: optional string` +### Beta Response Refusal Delta Event - The identifier of the actor that created the item. +- `BetaResponseRefusalDeltaEvent object { content_index, delta, item_id, 4 more }` - - `status: "in_progress" or "completed" or "incomplete"` + Emitted when there is a partial refusal text. - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + - `content_index: number` - - `"in_progress"` + The index of the content part that the refusal text is added to. - - `"completed"` + - `delta: string` - - `"incomplete"` + The refusal text that is added. - - `type: "shell_call_output"` + - `item_id: string` - The type of the shell call output. Always `shell_call_output`. + The ID of the output item that the refusal text is added to. - - `"shell_call_output"` + - `output_index: number` + + The index of the output item that the refusal text is added to. + + - `sequence_number: number` + + The sequence number of this event. + + - `type: "response.refusal.delta"` + + The type of the event. Always `response.refusal.delta`. + + - `"response.refusal.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 }` +### Beta Response Refusal Done Event - The execution context that produced this tool call. +- `BetaResponseRefusalDoneEvent object { content_index, item_id, output_index, 4 more }` - - `Direct object { type }` + Emitted when refusal text is finalized. - - `type: "direct"` + - `content_index: number` - - `"direct"` + The index of the content part that the refusal text is finalized. - - `Program object { caller_id, type }` + - `item_id: string` - - `caller_id: string` + The ID of the output item that the refusal text is finalized. - The call ID of the program item that produced this tool call. + - `output_index: number` - - `type: "program"` + The index of the output item that the refusal text is finalized. - - `"program"` + - `refusal: string` - - `created_by: optional string` + The refusal text that is finalized. - The identifier of the actor that created the item. + - `sequence_number: number` - - `ApplyPatchCall object { id, call_id, operation, 5 more }` + The sequence number of this event. - A tool call that applies file diffs by creating, deleting, or updating files. + - `type: "response.refusal.done"` - - `id: string` + The type of the event. Always `response.refusal.done`. - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `"response.refusal.done"` - - `call_id: string` + - `agent: optional object { agent_name }` - The unique ID of the apply patch tool call generated by the model. + The agent that owns this multi-agent streaming event. - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + - `agent_name: string` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + The canonical name of the agent that produced this item. - - `CreateFile object { diff, path, type }` +### Beta Response Status - Instruction describing how to create a file via the apply_patch tool. +- `BetaResponseStatus = "completed" or "failed" or "in_progress" or 3 more` - - `diff: string` + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. + + - `"completed"` + + - `"failed"` + + - `"in_progress"` + + - `"cancelled"` + + - `"queued"` + + - `"incomplete"` + +### Beta Response Stream Event + +- `BetaResponseStreamEvent = BetaResponseAudioDeltaEvent or BetaResponseAudioDoneEvent or BetaResponseAudioTranscriptDeltaEvent or 50 more` + + Emitted when there is a partial audio response. + + - `BetaResponseAudioDeltaEvent object { delta, sequence_number, type, agent }` + + Emitted when there is a partial audio response. + + - `delta: string` + + A chunk of Base64 encoded response audio bytes. - Diff to apply. + - `sequence_number: number` - - `path: string` + A sequence number for this chunk of the stream response. - Path of the file to create. + - `type: "response.audio.delta"` - - `type: "create_file"` + The type of the event. Always `response.audio.delta`. - Create a new file with the provided diff. + - `"response.audio.delta"` - - `"create_file"` + - `agent: optional object { agent_name }` - - `DeleteFile object { path, type }` + The agent that owns this multi-agent streaming event. - Instruction describing how to delete a file via the apply_patch tool. + - `agent_name: string` - - `path: string` + The canonical name of the agent that produced this item. - Path of the file to delete. + - `BetaResponseAudioDoneEvent object { sequence_number, type, agent }` - - `type: "delete_file"` + Emitted when the audio response is complete. - Delete the specified file. + - `sequence_number: number` - - `"delete_file"` + The sequence number of the delta. - - `UpdateFile object { diff, path, type }` + - `type: "response.audio.done"` - Instruction describing how to update a file via the apply_patch tool. + The type of the event. Always `response.audio.done`. - - `diff: string` + - `"response.audio.done"` - Diff to apply. + - `agent: optional object { agent_name }` - - `path: string` + The agent that owns this multi-agent streaming event. - Path of the file to update. + - `agent_name: string` - - `type: "update_file"` + The canonical name of the agent that produced this item. - Update an existing file with the provided diff. + - `BetaResponseAudioTranscriptDeltaEvent object { delta, sequence_number, type, agent }` - - `"update_file"` + Emitted when there is a partial transcript of audio. - - `status: "in_progress" or "completed"` + - `delta: string` - The status of the apply patch tool call. One of `in_progress` or `completed`. + The partial transcript of the audio response. - - `"in_progress"` + - `sequence_number: number` - - `"completed"` + The sequence number of this event. - - `type: "apply_patch_call"` + - `type: "response.audio.transcript.delta"` - The type of the item. Always `apply_patch_call`. + The type of the event. Always `response.audio.transcript.delta`. - - `"apply_patch_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 }` - - The execution context that produced this tool call. + - `BetaResponseAudioTranscriptDoneEvent object { sequence_number, type, agent }` - - `Direct object { type }` + Emitted when the full audio transcript is completed. - - `type: "direct"` + - `sequence_number: number` - - `"direct"` + The sequence number of this event. - - `Program object { caller_id, type }` + - `type: "response.audio.transcript.done"` - - `caller_id: string` + The type of the event. Always `response.audio.transcript.done`. - The call ID of the program item that produced this tool call. + - `"response.audio.transcript.done"` - - `type: "program"` + - `agent: optional object { agent_name }` - - `"program"` + The agent that owns this multi-agent streaming event. - - `created_by: optional string` + - `agent_name: string` - The ID of the entity that created this tool call. + The canonical name of the agent that produced this item. - - `ApplyPatchCallOutput object { id, call_id, status, 5 more }` + - `BetaResponseCodeInterpreterCallCodeDeltaEvent object { delta, item_id, output_index, 3 more }` - The output emitted by an apply patch tool call. + Emitted when a partial code snippet is streamed by the code interpreter. - - `id: string` + - `delta: string` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + The partial code snippet being streamed by the code interpreter. - - `call_id: string` + - `item_id: string` - The unique ID of the apply patch tool call generated by the model. + The unique identifier of the code interpreter tool call item. - - `status: "completed" or "failed"` + - `output_index: number` - The status of the apply patch tool call output. One of `completed` or `failed`. + The index of the output item in the response for which the code is being streamed. - - `"completed"` + - `sequence_number: number` - - `"failed"` + The sequence number of this event, used to order streaming events. - - `type: "apply_patch_call_output"` + - `type: "response.code_interpreter_call_code.delta"` - The type of the item. Always `apply_patch_call_output`. + The type of the event. Always `response.code_interpreter_call_code.delta`. - - `"apply_patch_call_output"` + - `"response.code_interpreter_call_code.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 }` + - `BetaResponseCodeInterpreterCallCodeDoneEvent object { code, item_id, output_index, 3 more }` - The execution context that produced this tool call. + Emitted when the code snippet is finalized by the code interpreter. - - `Direct object { type }` + - `code: string` - - `type: "direct"` + The final code snippet output by the code interpreter. - - `"direct"` + - `item_id: string` - - `Program object { caller_id, type }` + The unique identifier of the code interpreter tool call item. - - `caller_id: string` + - `output_index: number` - The call ID of the program item that produced this tool call. + The index of the output item in the response for which the code is finalized. - - `type: "program"` + - `sequence_number: number` - - `"program"` + The sequence number of this event, used to order streaming events. - - `created_by: optional string` + - `type: "response.code_interpreter_call_code.done"` - The ID of the entity that created this tool call output. + The type of the event. Always `response.code_interpreter_call_code.done`. - - `output: optional string` + - `"response.code_interpreter_call_code.done"` - Optional textual output returned by the apply patch tool. + - `agent: optional object { agent_name }` - - `McpCall object { id, arguments, name, 7 more }` + The agent that owns this multi-agent streaming event. - An invocation of a tool on an MCP server. + - `agent_name: string` - - `id: string` + The canonical name of the agent that produced this item. - The unique ID of the tool call. + - `BetaResponseCodeInterpreterCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` - - `arguments: string` + Emitted when the code interpreter call is completed. - A JSON string of the arguments passed to the tool. + - `item_id: string` - - `name: string` + The unique identifier of the code interpreter tool call item. - The name of the tool that was run. + - `output_index: number` - - `server_label: string` + The index of the output item in the response for which the code interpreter call is completed. - The label of the MCP server running the tool. + - `sequence_number: number` - - `type: "mcp_call"` + The sequence number of this event, used to order streaming events. - The type of the item. Always `mcp_call`. + - `type: "response.code_interpreter_call.completed"` - - `"mcp_call"` + The type of the event. Always `response.code_interpreter_call.completed`. + + - `"response.code_interpreter_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. - - `approval_request_id: optional string` + - `BetaResponseCodeInterpreterCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + Emitted when a code interpreter call is in progress. - - `error: optional string` + - `item_id: string` - The error from the tool call, if any. + The unique identifier of the code interpreter tool call item. - - `output: optional string` + - `output_index: number` - The output from the tool call. + The index of the output item in the response for which the code interpreter call is in progress. - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `sequence_number: number` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + The sequence number of this event, used to order streaming events. - - `"in_progress"` + - `type: "response.code_interpreter_call.in_progress"` - - `"completed"` + The type of the event. Always `response.code_interpreter_call.in_progress`. - - `"incomplete"` + - `"response.code_interpreter_call.in_progress"` - - `"calling"` + - `agent: optional object { agent_name }` - - `"failed"` + The agent that owns this multi-agent streaming event. - - `McpListTools object { id, server_label, tools, 3 more }` + - `agent_name: string` - A list of tools available on an MCP server. + The canonical name of the agent that produced this item. - - `id: string` + - `BetaResponseCodeInterpreterCallInterpretingEvent object { item_id, output_index, sequence_number, 2 more }` - The unique ID of the list. + Emitted when the code interpreter is actively interpreting the code snippet. - - `server_label: string` + - `item_id: string` - The label of the MCP server. + The unique identifier of the code interpreter tool call item. - - `tools: array of object { input_schema, name, annotations, description }` + - `output_index: number` - The tools available on the server. + The index of the output item in the response for which the code interpreter is interpreting code. - - `input_schema: unknown` + - `sequence_number: number` - The JSON schema describing the tool's input. + The sequence number of this event, used to order streaming events. - - `name: string` + - `type: "response.code_interpreter_call.interpreting"` - The name of the tool. + The type of the event. Always `response.code_interpreter_call.interpreting`. - - `annotations: optional unknown` + - `"response.code_interpreter_call.interpreting"` - Additional annotations about the tool. + - `agent: optional object { agent_name }` - - `description: optional string` + The agent that owns this multi-agent streaming event. - The description of the tool. + - `agent_name: string` - - `type: "mcp_list_tools"` + The canonical name of the agent that produced this item. - The type of the item. Always `mcp_list_tools`. + - `BetaResponseCompletedEvent object { response, sequence_number, type, agent }` - - `"mcp_list_tools"` + Emitted when the model response is complete. - - `agent: optional object { agent_name }` + - `response: BetaResponse` - The agent that produced this item. + Properties of the completed response. - - `agent_name: string` + - `id: string` - The canonical name of the agent that produced this item. + Unique identifier for this Response. - - `error: optional string` + - `created_at: number` - Error message if the server could not list tools. + Unix timestamp (in seconds) of when this Response was created. - - `McpApprovalRequest object { id, arguments, name, 3 more }` + - `error: BetaResponseError` - A request for human approval of a tool invocation. + An error object returned when the model fails to generate a Response. - - `id: string` + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 16 more` - The unique ID of the approval request. + The error code for the response. - - `arguments: string` + - `"server_error"` - A JSON string of arguments for the tool. + - `"rate_limit_exceeded"` - - `name: string` + - `"invalid_prompt"` - The name of the tool to run. + - `"bio_policy"` - - `server_label: string` + - `"vector_store_timeout"` - The label of the MCP server making the request. + - `"invalid_image"` - - `type: "mcp_approval_request"` + - `"invalid_image_format"` - The type of the item. Always `mcp_approval_request`. + - `"invalid_base64_image"` - - `"mcp_approval_request"` + - `"invalid_image_url"` - - `agent: optional object { agent_name }` + - `"image_too_large"` - The agent that produced this item. + - `"image_too_small"` - - `agent_name: string` + - `"image_parse_error"` - The canonical name of the agent that produced this item. + - `"image_content_policy_violation"` - - `McpApprovalResponse object { id, approval_request_id, approve, 3 more }` + - `"invalid_image_mode"` - A response to an MCP approval request. + - `"image_file_too_large"` - - `id: string` + - `"unsupported_image_media_type"` - The unique ID of the approval response + - `"empty_image_file"` - - `approval_request_id: string` + - `"failed_to_download_image"` - The ID of the approval request being answered. + - `"image_file_not_found"` - - `approve: boolean` + - `message: string` - Whether the request was approved. + A human-readable description of the error. - - `type: "mcp_approval_response"` + - `incomplete_details: object { reason }` - The type of the item. Always `mcp_approval_response`. + Details about why the response is incomplete. - - `"mcp_approval_response"` + - `reason: optional "max_output_tokens" or "content_filter"` - - `agent: optional object { agent_name }` + The reason why the response is incomplete. - The agent that produced this item. + - `"max_output_tokens"` - - `agent_name: string` + - `"content_filter"` - The canonical name of the agent that produced this item. + - `instructions: string or array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` - - `reason: optional string` + A system (or developer) message inserted into the model's context. - Optional reason for the decision. + 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. - - `CustomToolCall object { call_id, input, name, 5 more }` + - `string` - A call to a custom tool created by the model. + A text input to the model, equivalent to a text input with the + `developer` role. - - `call_id: string` + - `InputItemList = array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` - An identifier used to map this custom tool call to a tool call output. + A list of one or many input items to the model, containing + different content types. - - `input: string` + - `BetaEasyInputMessage object { content, role, phase, type }` - The input for the custom tool call generated by the model. + 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. - - `name: string` + - `content: string or BetaResponseInputMessageContentList` - The name of the custom tool being called. + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `type: "custom_tool_call"` + - `TextInput = string` - The type of the custom tool call. Always `custom_tool_call`. + A text input to the model. - - `"custom_tool_call"` + - `BetaResponseInputMessageContentList = array of BetaResponseInputContent` - - `id: optional string` + A list of one or many input items to the model, containing different content + types. - The unique ID of the custom tool call in the OpenAI platform. + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `agent: optional object { agent_name }` + A text input to the model. - The agent that produced this item. + - `text: string` - - `agent_name: string` + The text input to the model. - The canonical name of the agent that produced this item. + - `type: "input_text"` - - `caller: optional object { type } or object { caller_id, type }` + The type of the input item. Always `input_text`. - The execution context that produced this tool call. + - `"input_text"` - - `Direct object { type }` + - `prompt_cache_breakpoint: optional object { mode }` - - `type: "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. - - `"direct"` + - `mode: "explicit"` - - `Program object { caller_id, type }` + The breakpoint mode. Always `explicit`. - - `caller_id: string` + - `"explicit"` - The call ID of the program item that produced this tool call. + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `type: "program"` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `"program"` + - `detail: "low" or "high" or "auto" or "original"` - - `namespace: optional string` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The namespace of the custom tool being called. + - `"low"` - - `CustomToolCallOutput object { id, call_id, output, 5 more }` + - `"high"` - - `id: string` + - `"auto"` - The unique ID of the custom tool call output item. + - `"original"` - - `call_id: string` + - `type: "input_image"` - The call ID, used to map this custom tool call output to a custom tool call. + The type of the input item. Always `input_image`. - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `"input_image"` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `file_id: optional string` - - `StringOutput = string` + The ID of the file to be sent to the model. - A string of the output of the custom tool call. + - `image_url: optional string` - - `OutputContentList = array of 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. - Text, image, or file output of the custom tool call. + - `prompt_cache_breakpoint: optional object { mode }` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - A text input to the model. + - `mode: "explicit"` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + The breakpoint mode. Always `explicit`. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `"explicit"` - `BetaResponseInputFile object { type, detail, file_data, 4 more }` A file input to the model. - - `status: "in_progress" or "completed" or "incomplete"` + - `type: "input_file"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + 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: "custom_tool_call_output"` + - `"auto"` - The type of the custom tool call output. Always `custom_tool_call_output`. + - `"low"` - - `"custom_tool_call_output"` + - `"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. - - `caller: optional object { type } or object { caller_id, type }` + - `file_url: optional string` - The execution context that produced this tool call. + The URL of the file to be sent to the model. - - `Direct object { type }` + - `filename: optional string` - - `type: "direct"` + The name of the file to be sent to the model. - The caller type. Always `direct`. + - `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. - - `Program object { caller_id, type }` + - `mode: "explicit"` - - `caller_id: string` + The breakpoint mode. Always `explicit`. - The call ID of the program item that produced this tool call. + - `"explicit"` - - `type: "program"` + - `role: "user" or "assistant" or "system" or "developer"` - The caller type. Always `program`. + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - - `"program"` + - `"user"` - - `created_by: optional string` + - `"assistant"` - The identifier of the actor that created the item. + - `"system"` - - `output_index: number` + - `"developer"` - The index of the output item that was added. + - `phase: optional "commentary" or "final_answer"` - - `sequence_number: 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. - The sequence number of this event. + - `"commentary"` - - `type: "response.output_item.added"` + - `"final_answer"` - The type of the event. Always `response.output_item.added`. + - `type: optional "message"` - - `"response.output_item.added"` + 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"` + + - `"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 Item Done Event + - `status: optional "in_progress" or "completed" or "incomplete"` -- `BetaResponseOutputItemDoneEvent object { item, output_index, sequence_number, 2 more }` + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Emitted when an output item is marked done. + - `"in_progress"` - - `item: BetaResponseOutputItem` + - `"completed"` - The output item that was marked done. + - `"incomplete"` + + - `type: optional "message"` + + The type of the message input. Always set to `message`. + + - `"message"` - `BetaResponseOutputMessage object { id, content, role, 4 more }` @@ -159334,7 +158908,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The content of the output message. - - `BetaResponseOutputText object { annotations, text, type, logprobs }` + - `BetaResponseOutputText object { annotations, logprobs, text, type }` A text output from the model. @@ -159438,17 +159012,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"file_path"` - - `text: string` - - The text output from the model. - - - `type: "output_text"` - - The type of the output text. Always `output_text`. - - - `"output_text"` - - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - `token: string` @@ -159464,6 +159028,16 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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. @@ -159522,7 +159096,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `FileSearchCall object { id, queries, status, 3 more }` The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + [file search guide](/docs/guides/tools-file-search) for more information. - `id: string` @@ -159595,66 +159169,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](https://platform.openai.com/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. @@ -159665,371 +159209,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](https://platform.openai.com/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, text, type, logprobs }` + 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](https://platform.openai.com/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 }` @@ -160039,68 +159520,20 @@ 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. - - - `text: string` - - The text output from the model. - - - `type: "output_text"` - - The type of the output text. Always `output_text`. - - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` - - - `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 }` The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + [web search guide](/docs/guides/tools-web-search) for more information. - `id: string` @@ -160201,360 +159634,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](https://platform.openai.com/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 }` @@ -160564,138 +159986,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](https://platform.openai.com/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 array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` - - `text: string` + Citations associated with the text content. - The reasoning text from the model. + - `array of 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 - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `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"` + - `array of 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"` + - `array of 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 }` @@ -160705,44 +160116,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. @@ -160751,21 +160140,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. @@ -160773,9 +160152,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"` @@ -160783,9 +160162,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 }` @@ -161048,7 +160429,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-web-search). + [web search tool](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -161108,7 +160489,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -161160,7 +160541,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -161384,19 +160765,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `background: optional "transparent" or "opaque" or "auto"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. - - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. - - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - `"transparent"` @@ -161425,13 +160795,13 @@ curl -X POST https://api.openai.com/v1/responses/compact \ Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `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-2" or 3 more` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` The image generation model to use. Default: `gpt-image-1`. @@ -161439,14 +160809,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"gpt-image-1-mini"` - - `"gpt-image-2"` - - - `"gpt-image-2-2026-04-21"` - - `"gpt-image-1.5"` - - `"chatgpt-image-latest"` - - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -161661,7 +161025,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -161775,7 +161139,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -161945,10 +161309,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. @@ -161957,39 +161325,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 }` @@ -162252,7 +161620,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-web-search). + [web search tool](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -162312,7 +161680,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -162364,7 +161732,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -162556,19 +161924,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `background: optional "transparent" or "opaque" or "auto"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. - - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. - - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - `"transparent"` @@ -162597,13 +161954,13 @@ curl -X POST https://api.openai.com/v1/responses/compact \ Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `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-2" or 3 more` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` The image generation model to use. Default: `gpt-image-1`. @@ -162611,14 +161968,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"gpt-image-1-mini"` - - `"gpt-image-2"` - - - `"gpt-image-2-2026-04-21"` - - `"gpt-image-1.5"` - - `"chatgpt-image-latest"` - - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -162715,7 +162066,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -162829,7 +162180,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -162999,10 +162350,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. @@ -163011,17 +162366,82 @@ 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](https://platform.openai.com/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 - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `Compaction object { encrypted_content, type, id, 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"` @@ -163029,6 +162449,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. @@ -163037,10 +162461,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. @@ -163248,1548 +162668,789 @@ 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"` - - - `"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` - - 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 - - - `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. - - - `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` - - Exit code from the shell process. - - - `type: "exit"` - - The outcome type. Always `exit`. - - - `"exit"` - - - `stderr: string` - - The standard error output that was captured. - - - `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"` - - - `type: "shell_call_output"` - - The type of the shell call output. Always `shell_call_output`. - - - `"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"` - - - `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](https://platform.openai.com/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 + - `status: optional "in_progress" or "completed" or "incomplete"` -- `BetaResponseOutputMessage object { id, content, role, 4 more }` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - An output message from the model. + - `"in_progress"` - - `id: string` + - `"completed"` - The unique ID of the output message. + - `"incomplete"` - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + - `ShellCall object { action, call_id, type, 5 more }` - The content of the output message. + A tool representing a request to execute one or more shell commands. - - `BetaResponseOutputText object { annotations, text, type, logprobs }` + - `action: object { commands, max_output_length, timeout_ms }` - A text output from the model. + The shell commands and limits that describe how to run the tool call. - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + - `commands: array of string` - The annotations of the text output. + Ordered shell commands for the execution environment to run. - - `FileCitation object { file_id, filename, index, type }` + - `max_output_length: optional number` - A citation to a file. + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - - `file_id: string` + - `timeout_ms: optional number` - The ID of the file. + Maximum wall-clock time in milliseconds to allow the shell commands to run. - - `filename: string` + - `call_id: string` - The filename of the file cited. + The unique ID of the shell tool call generated by the model. - - `index: number` + - `type: "shell_call"` - The index of the file in the list of files. + The type of the item. Always `shell_call`. - - `type: "file_citation"` + - `"shell_call"` - The type of the file citation. Always `file_citation`. + - `id: optional string` - - `"file_citation"` + The unique ID of the shell tool call. Populated when this item is returned via API. - - `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"` + The caller type. Always `direct`. - The type of the URL citation. Always `url_citation`. + - `"direct"` - - `"url_citation"` + - `Program object { caller_id, type }` - - `url: string` + - `caller_id: string` - The URL of the web resource. + The call ID of the program item that produced this tool call. - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + - `type: "program"` - A citation for a container file used to generate a model response. + The caller type. Always `program`. - - `container_id: string` + - `"program"` - The ID of the container file. + - `environment: optional BetaLocalEnvironment or BetaContainerReference` - - `end_index: number` + The environment to execute the shell commands in. - The index of the last character of the container file citation in the message. + - `BetaLocalEnvironment object { type, skills }` - - `file_id: string` + - `BetaContainerReference object { container_id, type }` - The ID of the file. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `filename: string` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - 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"` + - `ShellCallOutput object { call_id, output, type, 5 more }` - The type of the container file citation. Always `container_file_citation`. + The streamed output items emitted by a shell tool call. - - `"container_file_citation"` + - `call_id: string` - - `FilePath object { file_id, index, type }` + The unique ID of the shell tool call generated by the model. - A path to a file. + - `output: array of BetaResponseFunctionShellCallOutputContent` - - `file_id: string` + Captured chunks of stdout and stderr output, along with their associated outcomes. - The ID of the file. + - `outcome: object { type } or object { exit_code, type }` - - `index: number` + The exit or timeout outcome associated with this shell call. - The index of the file in the list of files. + - `Timeout object { type }` - - `type: "file_path"` + Indicates that the shell call exceeded its configured time limit. - The type of the file path. Always `file_path`. + - `type: "timeout"` - - `"file_path"` + The outcome type. Always `timeout`. - - `text: string` + - `"timeout"` - The text output from the model. + - `Exit object { exit_code, type }` - - `type: "output_text"` + Indicates that the shell commands finished and returned an exit code. - The type of the output text. Always `output_text`. + - `exit_code: number` - - `"output_text"` + The exit code returned by the shell process. - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + - `type: "exit"` - - `token: string` + The outcome type. Always `exit`. - - `bytes: array of number` + - `"exit"` - - `logprob: number` + - `stderr: string` - - `top_logprobs: array of object { token, bytes, logprob }` + Captured stderr output for the shell call. - - `token: string` + - `stdout: string` - - `bytes: array of number` + Captured stdout output for the shell call. - - `logprob: number` + - `type: "shell_call_output"` - - `BetaResponseOutputRefusal object { refusal, type }` + The type of the item. Always `shell_call_output`. - A refusal from the model. + - `"shell_call_output"` - - `refusal: string` + - `id: optional string` - The refusal explanation from the model. + The unique ID of the shell tool call output. Populated when this item is returned via API. - - `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`. + - `caller: optional object { type } or object { caller_id, type }` - - `"assistant"` + The execution context that produced this tool call. - - `status: "in_progress" or "completed" or "incomplete"` + - `Direct object { type }` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `type: "direct"` - - `"in_progress"` + The caller type. Always `direct`. - - `"completed"` + - `"direct"` - - `"incomplete"` + - `Program object { caller_id, type }` - - `type: "message"` + - `caller_id: string` - The type of the output message. Always `message`. + The call ID of the program item that produced this tool call. - - `"message"` + - `type: "program"` - - `agent: optional object { agent_name }` + The caller type. Always `program`. - The agent that produced this item. + - `"program"` - - `agent_name: string` + - `max_output_length: optional number` - The canonical name of the agent that produced this item. + The maximum number of UTF-8 characters captured for this shell call's combined output. - - `phase: optional "commentary" or "final_answer"` + - `status: optional "in_progress" or "completed" or "incomplete"` - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + The status of the shell call output. - - `"commentary"` + - `"in_progress"` - - `"final_answer"` + - `"completed"` -### Beta Response Output Refusal + - `"incomplete"` -- `BetaResponseOutputRefusal object { refusal, type }` + - `ApplyPatchCall object { call_id, operation, status, 4 more }` - A refusal from the model. + A tool call representing a request to create, delete, or update files using diff patches. - - `refusal: string` + - `call_id: string` - The refusal explanation from the model. + The unique ID of the apply patch tool call generated by the model. - - `type: "refusal"` + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - The type of the refusal. Always `refusal`. + The specific create, delete, or update instruction for the apply_patch tool call. - - `"refusal"` + - `CreateFile object { diff, path, type }` -### Beta Response Output Text + Instruction for creating a new file via the apply_patch tool. -- `BetaResponseOutputText object { annotations, text, type, logprobs }` + - `diff: string` - A text output from the model. + Unified diff content to apply when creating the 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 }` + - `path: string` - The annotations of the text output. + Path of the file to create relative to the workspace root. - - `FileCitation object { file_id, filename, index, type }` + - `type: "create_file"` - A citation to a file. + The operation type. Always `create_file`. - - `file_id: string` + - `"create_file"` - The ID of the file. + - `DeleteFile object { path, type }` - - `filename: string` + Instruction for deleting an existing file via the apply_patch tool. - The filename of the file cited. + - `path: string` - - `index: number` + Path of the file to delete relative to the workspace root. - The index of the file in the list of files. + - `type: "delete_file"` - - `type: "file_citation"` + The operation type. Always `delete_file`. - The type of the file citation. Always `file_citation`. + - `"delete_file"` - - `"file_citation"` + - `UpdateFile object { diff, path, type }` - - `URLCitation object { end_index, start_index, title, 2 more }` + Instruction for updating an existing file via the apply_patch tool. - A citation for a web resource used to generate a model response. + - `diff: string` - - `end_index: number` + Unified diff content to apply to the existing file. - The index of the last character of the URL citation in the message. + - `path: string` - - `start_index: number` + Path of the file to update relative to the workspace root. - The index of the first character of the URL citation in the message. + - `type: "update_file"` - - `title: string` + The operation type. Always `update_file`. - The title of the web resource. + - `"update_file"` - - `type: "url_citation"` + - `status: "in_progress" or "completed"` - The type of the URL citation. Always `url_citation`. + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `"url_citation"` + - `"in_progress"` - - `url: string` + - `"completed"` - The URL of the web resource. + - `type: "apply_patch_call"` - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + The type of the item. Always `apply_patch_call`. - A citation for a container file used to generate a model response. + - `"apply_patch_call"` - - `container_id: string` + - `id: optional string` - The ID of the container file. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `end_index: number` + - `agent: optional object { agent_name }` - The index of the last character of the container file citation in the message. + 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` + - `caller: optional object { type } or object { caller_id, type }` - The filename of the container file cited. + The execution context that produced this tool call. - - `start_index: number` + - `Direct object { type }` - The index of the first character of the container file citation in the message. + - `type: "direct"` - - `type: "container_file_citation"` + The caller type. Always `direct`. - The type of the container file citation. Always `container_file_citation`. + - `"direct"` - - `"container_file_citation"` + - `Program object { caller_id, type }` - - `FilePath object { file_id, index, type }` + - `caller_id: string` - A path to a file. + The call ID of the program item that produced this tool call. - - `file_id: string` + - `type: "program"` - The ID of the file. + The caller type. Always `program`. - - `index: number` + - `"program"` - The index of the file in the list of files. + - `ApplyPatchCallOutput object { call_id, status, type, 4 more }` - - `type: "file_path"` + The streamed output emitted by an apply patch tool call. - The type of the file path. Always `file_path`. + - `call_id: string` - - `"file_path"` + The unique ID of the apply patch tool call generated by the model. - - `text: string` + - `status: "completed" or "failed"` - The text output from the model. + The status of the apply patch tool call output. One of `completed` or `failed`. - - `type: "output_text"` + - `"completed"` - The type of the output text. Always `output_text`. + - `"failed"` - - `"output_text"` + - `type: "apply_patch_call_output"` - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + The type of the item. Always `apply_patch_call_output`. - - `token: string` + - `"apply_patch_call_output"` - - `bytes: array of number` + - `id: optional string` - - `logprob: number` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `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. -### Beta Response Output Text Annotation Added Event + - `caller: optional object { type } or object { caller_id, type }` -- `BetaResponseOutputTextAnnotationAddedEvent object { annotation, annotation_index, content_index, 5 more }` + The execution context that produced this tool call. - Emitted when an annotation is added to output text content. + - `Direct object { type }` - - `annotation: unknown` + - `type: "direct"` - The annotation object being added. (See annotation schema for details.) + The caller type. Always `direct`. - - `annotation_index: number` + - `"direct"` - The index of the annotation within the content part. + - `Program object { caller_id, type }` - - `content_index: number` + - `caller_id: string` - The index of the content part within the output item. + The call ID of the program item that produced this tool call. - - `item_id: string` + - `type: "program"` - The unique identifier of the item to which the annotation is being added. + The caller type. Always `program`. - - `output_index: number` + - `"program"` - The index of the output item in the response's output array. + - `output: optional string` - - `sequence_number: number` + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - The sequence number of this event. + - `McpListTools object { id, server_label, tools, 3 more }` - - `type: "response.output_text.annotation.added"` + A list of tools available on an MCP server. - The type of the event. Always 'response.output_text.annotation.added'. + - `id: string` - - `"response.output_text.annotation.added"` + The unique ID of the list. - - `agent: optional object { agent_name }` + - `server_label: string` - The agent that owns this multi-agent streaming event. + The label of the MCP server. - - `agent_name: string` + - `tools: array of object { input_schema, name, annotations, description }` - The canonical name of the agent that produced this item. + The tools available on the server. -### Beta Response Prompt + - `input_schema: unknown` -- `BetaResponsePrompt object { id, variables, version }` + The JSON schema describing the tool's input. - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + - `name: string` - - `id: string` + The name of the tool. - The unique identifier of the prompt template to use. + - `annotations: optional unknown` - - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` + Additional annotations about the tool. - 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. + - `description: optional string` - - `string` + The description of the tool. - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `type: "mcp_list_tools"` - A text input to the model. + The type of the item. Always `mcp_list_tools`. - - `text: string` + - `"mcp_list_tools"` - 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 }` + - `error: 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. + Error message if the server could not list tools. - - `mode: "explicit"` + - `McpApprovalRequest object { id, arguments, name, 3 more }` - The breakpoint mode. Always `explicit`. + A request for human approval of a tool invocation. - - `"explicit"` + - `id: string` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + The unique ID of the approval request. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `arguments: string` - - `detail: "low" or "high" or "auto" or "original"` + A JSON string of arguments for the tool. - 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 tool to run. - - `"high"` + - `server_label: string` - - `"auto"` + The label of the MCP server making the request. - - `"original"` + - `type: "mcp_approval_request"` - - `type: "input_image"` + The type of the item. Always `mcp_approval_request`. - The type of the input item. Always `input_image`. + - `"mcp_approval_request"` - - `"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. + - `McpApprovalResponse object { approval_request_id, approve, type, 3 more }` - - `prompt_cache_breakpoint: optional object { mode }` + A response to an MCP approval request. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `approval_request_id: string` - - `mode: "explicit"` + The ID of the approval request being answered. - The breakpoint mode. Always `explicit`. + - `approve: boolean` - - `"explicit"` + Whether the request was approved. - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `type: "mcp_approval_response"` - A file input to the model. + The type of the item. Always `mcp_approval_response`. - - `type: "input_file"` + - `"mcp_approval_response"` - The type of the input item. Always `input_file`. + - `id: optional string` - - `"input_file"` + The unique ID of the approval response - - `detail: optional "auto" or "low" or "high"` + - `agent: optional object { agent_name }` - 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 agent that produced this item. - - `"auto"` + - `agent_name: string` - - `"low"` + The canonical name of the agent that produced this item. - - `"high"` + - `reason: optional string` - - `file_data: optional string` + Optional reason for the decision. - The content of the file to be sent to the model. + - `McpCall object { id, arguments, name, 7 more }` - - `file_id: optional string` + An invocation of a tool on an MCP server. - The ID of the file to be sent to the model. + - `id: string` - - `file_url: optional string` + The unique ID of the tool call. - The URL of the file to be sent to the model. + - `arguments: string` - - `filename: optional string` + A JSON string of the arguments passed to the tool. - The name of the file to be sent to the model. + - `name: string` - - `prompt_cache_breakpoint: optional object { mode }` + The name of the tool that was 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. + - `server_label: string` - - `mode: "explicit"` + The label of the MCP server running the tool. - The breakpoint mode. Always `explicit`. + - `type: "mcp_call"` - - `"explicit"` + The type of the item. Always `mcp_call`. - - `version: optional string` + - `"mcp_call"` - Optional version of the prompt template. + - `agent: optional object { agent_name }` -### Beta Response Queued Event + The agent that produced this item. -- `BetaResponseQueuedEvent object { response, sequence_number, type, agent }` + - `agent_name: string` - Emitted when a response is queued and waiting to be processed. + The canonical name of the agent that produced this item. - - `response: BetaResponse` + - `approval_request_id: optional string` - The full response object that is queued. + 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. - - `id: string` + - `error: optional string` - Unique identifier for this Response. + The error from the tool call, if any. - - `created_at: number` + - `output: optional string` - Unix timestamp (in seconds) of when this Response was created. + The output from the tool call. - - `error: BetaResponseError` + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - An error object returned when the model fails to generate a Response. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 16 more` + - `"in_progress"` - The error code for the response. + - `"completed"` - - `"server_error"` + - `"incomplete"` - - `"rate_limit_exceeded"` + - `"calling"` - - `"invalid_prompt"` + - `"failed"` - - `"bio_policy"` + - `CustomToolCallOutput object { call_id, output, type, 3 more }` - - `"vector_store_timeout"` + The output of a custom tool call from your code, being sent back to the model. - - `"invalid_image"` + - `call_id: string` - - `"invalid_image_format"` + The call ID, used to map this custom tool call output to a custom tool call. - - `"invalid_base64_image"` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `"invalid_image_url"` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `"image_too_large"` + - `StringOutput = string` - - `"image_too_small"` + A string of the output of the custom tool call. - - `"image_parse_error"` + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `"image_content_policy_violation"` + Text, image, or file output of the custom tool call. - - `"invalid_image_mode"` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `"image_file_too_large"` + A text input to the model. - - `"unsupported_image_media_type"` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `"empty_image_file"` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `"failed_to_download_image"` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `"image_file_not_found"` + A file input to the model. - - `message: string` + - `type: "custom_tool_call_output"` - A human-readable description of the error. + The type of the custom tool call output. Always `custom_tool_call_output`. - - `incomplete_details: object { reason }` + - `"custom_tool_call_output"` - Details about why the response is incomplete. + - `id: optional string` - - `reason: optional "max_output_tokens" or "content_filter"` + The unique ID of the custom tool call output in the OpenAI platform. - The reason why the response is incomplete. + - `agent: optional object { agent_name }` - - `"max_output_tokens"` + The agent that produced this item. - - `"content_filter"` + - `agent_name: string` - - `instructions: string or 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 system (or developer) message inserted into the model's context. + - `caller: optional object { type } or object { caller_id, 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 execution context that produced this tool call. - - `string` + - `Direct object { type }` - A text input to the model, equivalent to a text input with the - `developer` role. + - `type: "direct"` - - `InputItemList = array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + The caller type. Always `direct`. - A list of one or many input items to the model, containing - different content types. + - `"direct"` - - `BetaEasyInputMessage object { content, role, phase, type }` + - `Program object { caller_id, 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. + - `caller_id: string` - - `content: string or BetaResponseInputMessageContentList` + The call ID of the program item that produced this tool call. - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + - `type: "program"` - - `TextInput = string` + The caller type. Always `program`. - A text input to the model. + - `"program"` - - `BetaResponseInputMessageContentList = array of BetaResponseInputContent` + - `CustomToolCall object { call_id, input, name, 5 more }` - A list of one or many input items to the model, containing different content - types. + A call to a custom tool created by the model. - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `call_id: string` - A text input to the model. + An identifier used to map this custom tool call to a tool call output. - - `text: string` + - `input: string` - The text input to the model. + The input for the custom tool call generated by the model. - - `type: "input_text"` + - `name: string` - The type of the input item. Always `input_text`. + The name of the custom tool being called. - - `"input_text"` + - `type: "custom_tool_call"` - - `prompt_cache_breakpoint: optional object { mode }` + The type of the custom tool call. Always `custom_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. + - `"custom_tool_call"` - - `mode: "explicit"` + - `id: optional string` - The breakpoint mode. Always `explicit`. + The unique ID of the custom tool call in the OpenAI platform. - - `"explicit"` + - `agent: optional object { agent_name }` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + The agent that produced this item. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `agent_name: string` - - `detail: "low" or "high" or "auto" or "original"` + The canonical name of the agent that produced this item. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `caller: optional object { type } or object { caller_id, type }` - - `"low"` + The execution context that produced this tool call. - - `"high"` + - `Direct object { type }` - - `"auto"` + - `type: "direct"` - - `"original"` + - `"direct"` - - `type: "input_image"` + - `Program object { caller_id, type }` - The type of the input item. Always `input_image`. + - `caller_id: string` - - `"input_image"` + The call ID of the program item that produced this tool call. - - `file_id: optional string` + - `type: "program"` - The ID of the file to be sent to the model. + - `"program"` - - `image_url: optional string` + - `namespace: 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 namespace of the custom tool being called. - - `prompt_cache_breakpoint: optional object { mode }` + - `CompactionTrigger object { type, 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. + Compacts the current context. Must be the final input item. - - `mode: "explicit"` + - `type: "compaction_trigger"` - The breakpoint mode. Always `explicit`. + The type of the item. Always `compaction_trigger`. - - `"explicit"` + - `"compaction_trigger"` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `agent: optional object { agent_name }` - A file input to the model. + The agent that produced this item. - - `type: "input_file"` + - `agent_name: string` - The type of the input item. Always `input_file`. + The canonical name of the agent that produced this item. - - `"input_file"` + - `ItemReference object { id, agent, type }` - - `detail: optional "auto" or "low" or "high"` + An internal identifier for an item to reference. - 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 ID of the item to reference. - - `"low"` + - `agent: optional object { agent_name }` - - `"high"` + The agent that produced this item. - - `file_data: optional string` + - `agent_name: string` - The content of the file to be sent to the model. + The canonical name of the agent that produced this item. - - `file_id: optional string` + - `type: optional "item_reference"` - The ID of the file to be sent to the model. + The type of item to reference. Always `item_reference`. - - `file_url: optional string` + - `"item_reference"` - The URL of the file to be sent to the model. + - `Program object { id, call_id, code, 3 more }` - - `filename: optional string` + - `id: string` - The name of the file to be sent to the model. + The unique ID of this program item. - - `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 stable call ID of the program item. - - `mode: "explicit"` + - `code: string` - The breakpoint mode. Always `explicit`. + The JavaScript source executed by programmatic tool calling. - - `"explicit"` + - `fingerprint: string` - - `role: "user" or "assistant" or "system" or "developer"` + Opaque program replay fingerprint that must be round-tripped. - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + - `type: "program"` - - `"user"` + The item type. Always `program`. - - `"assistant"` + - `"program"` - - `"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"` + - `ProgramOutput object { id, call_id, result, 3 more }` - - `"final_answer"` + - `id: string` - - `type: optional "message"` + The unique ID of this program output item. - The type of the message input. Always `message`. + - `call_id: string` - - `"message"` + The call ID of the program item. - - `Message object { content, role, agent, 2 more }` + - `result: 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 result produced by the program item. - - `content: BetaResponseInputMessageContentList` + - `status: "completed" or "incomplete"` - A list of one or many input items to the model, containing different content - types. + The terminal status of the program output. - - `role: "user" or "system" or "developer"` + - `"completed"` - The role of the message input. One of `user`, `system`, or `developer`. + - `"incomplete"` - - `"user"` + - `type: "program_output"` - - `"system"` + The item type. Always `program_output`. - - `"developer"` + - `"program_output"` - `agent: optional object { agent_name }` @@ -164799,224 +163460,246 @@ 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, text, type, logprobs }` + - `"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"` - - `text: string` + - `"codex-mini-latest"` - The text output from the model. + - `"gpt-4o-mini"` - - `type: "output_text"` + - `"gpt-4o-mini-2024-07-18"` - The type of the output text. Always `output_text`. + - `"gpt-4-turbo"` - - `"output_text"` + - `"gpt-4-turbo-2024-04-09"` - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + - `"gpt-4-0125-preview"` - - `token: string` + - `"gpt-4-turbo-preview"` - - `bytes: array of number` + - `"gpt-4-1106-preview"` - - `logprob: number` + - `"gpt-4-vision-preview"` - - `top_logprobs: array of object { token, bytes, logprob }` + - `"gpt-4"` - - `token: string` + - `"gpt-4-0314"` - - `bytes: array of number` + - `"gpt-4-0613"` - - `logprob: number` + - `"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` + + - `object: "response"` + + 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. - - `"commentary"` + - `BetaResponseOutputMessage object { id, content, role, 4 more }` - - `"final_answer"` + An output message from the model. - `FileSearchCall object { id, queries, status, 3 more }` The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + [file search guide](/docs/guides/tools-file-search) for more information. - `id: string` @@ -165089,36 +163772,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](https://platform.openai.com/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. @@ -165129,247 +163842,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 }` @@ -165379,58 +164118,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 }` @@ -165440,20 +164176,10 @@ 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 - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + [web search guide](/docs/guides/tools-web-search) for more information. - `id: string` @@ -165554,66 +164280,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](https://platform.openai.com/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. @@ -165624,145 +164320,121 @@ 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 BetaResponseFunctionCallOutputItemList` - - Text, image, or file output of the function tool call. - - - `string` - - A JSON string of the output of the function tool call. - - - `BetaResponseFunctionCallOutputItemList = array of BetaResponseFunctionCallOutputItem` - - 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`. + - `type: "computer_call"` - - `"input_text"` + The type of the computer call. Always `computer_call`. - - `prompt_cache_breakpoint: optional object { mode }` + - `"computer_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. + - `action: optional BetaComputerAction` - - `mode: "explicit"` + A click action. - The breakpoint mode. Always `explicit`. + - `actions: optional BetaComputerActionList` - - `"explicit"` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` + - `agent: optional object { agent_name }` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + 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"` + - `ComputerCallOutput object { id, call_id, output, 5 more }` - - `detail: optional "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 computer call tool output. - - `"low"` + - `call_id: string` - - `"high"` + The ID of the computer tool call that produced the output. - - `"auto"` + - `output: BetaResponseComputerToolCallOutputScreenshot` - - `"original"` + A computer screenshot image used with the computer use tool. - - `file_id: optional string` + - `status: "completed" or "incomplete" or "failed" or "in_progress"` - The ID of the file to be sent to the model. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `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 }` + - `"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. + - `"in_progress"` - - `mode: "explicit"` + - `type: "computer_call_output"` - The breakpoint mode. Always `explicit`. + The type of the computer tool call output. Always `computer_call_output`. - - `"explicit"` + - `"computer_call_output"` - - `BetaResponseInputFileContent object { type, detail, file_data, 4 more }` + - `acknowledged_safety_checks: optional array of object { id, code, message }` - A file input to the model. + The safety checks reported by the API that have been acknowledged by the + developer. - - `type: "input_file"` + - `id: string` - The type of the input item. Always `input_file`. + The ID of the pending safety check. - - `"input_file"` + - `code: optional string` - - `detail: optional "auto" or "low" or "high"` + The type of the pending safety check. - 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`. + - `message: optional string` - - `"auto"` + Details about the pending safety check. - - `"low"` + - `agent: optional object { agent_name }` - - `"high"` + The agent that produced this item. - - `file_data: optional string` + - `agent_name: string` - The base64-encoded data of the file to be sent to the model. + The canonical name of the agent that produced this item. - - `file_id: optional string` + - `created_by: optional string` - The ID of the file to be sent to the model. + The identifier of the actor that created the item. - - `file_url: optional string` + - `Reasoning object { id, summary, type, 4 more }` - The URL of the file to be sent to 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). - - `filename: optional string` + - `id: string` - The name of the file to be sent to the model. + The unique identifier of the reasoning content. - - `prompt_cache_breakpoint: optional object { mode }` + - `summary: array of object { text, 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. + Reasoning summary content. - - `mode: "explicit"` + - `text: string` - The breakpoint mode. Always `explicit`. + A summary of the reasoning output from the model so far. - - `"explicit"` + - `type: "summary_text"` - - `type: "function_call_output"` + The type of the object. Always `summary_text`. - The type of the function tool call output. Always `function_call_output`. + - `"summary_text"` - - `"function_call_output"` + - `type: "reasoning"` - - `id: optional string` + The type of the object. Always `reasoning`. - The unique ID of the function tool call output. Populated when this item is returned via API. + - `"reasoning"` - `agent: optional object { agent_name }` @@ -165772,33 +164444,29 @@ 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"` + - `content: optional array of object { text, type }` - The caller type. Always `direct`. + Reasoning text content. - - `"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"` - The caller type. Always `program`. + - `encrypted_content: optional string` - - `"program"` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - `status: optional "in_progress" or "completed" or "incomplete"` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `"in_progress"` @@ -165806,53 +164474,29 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"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](https://platform.openai.com/docs/guides/vision) - - - `EncryptedContent object { encrypted_content, type }` - - Opaque encrypted content that Responses API decrypts inside trusted model execution. - - - `encrypted_content: string` + - `Program object { id, call_id, code, 3 more }` - Opaque encrypted content. + - `id: string` - - `type: "encrypted_content"` + The unique ID of the program item. - The type of the input item. Always `encrypted_content`. + - `call_id: string` - - `"encrypted_content"` + The stable call ID of the program item. - - `recipient: string` + - `code: string` - The destination agent identity. + The JavaScript source executed by programmatic tool calling. - - `type: "agent_message"` + - `fingerprint: string` - The item type. Always `agent_message`. + Opaque program replay fingerprint that must be round-tripped. - - `"agent_message"` + - `type: "program"` - - `id: optional string` + The type of the item. Always `program`. - The unique ID of this agent message item. + - `"program"` - `agent: optional object { agent_name }` @@ -165862,41 +164506,33 @@ 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. - - - `"spawn_agent"` - - - `"interrupt_agent"` + - `ProgramOutput object { id, call_id, result, 3 more }` - - `"list_agents"` + - `id: string` - - `"send_message"` + The unique ID of the program output item. - - `"followup_task"` + - `call_id: string` - - `"wait_agent"` + The call ID of the program item. - - `arguments: string` + - `result: string` - The action arguments as a JSON string. + The result produced by the program item. - - `call_id: string` + - `status: "completed" or "incomplete"` - The unique ID linking this call to its output. + The terminal status of the program output item. - - `type: "multi_agent_call"` + - `"completed"` - The item type. Always `multi_agent_call`. + - `"incomplete"` - - `"multi_agent_call"` + - `type: "program_output"` - - `id: optional string` + The type of the item. Always `program_output`. - The unique ID of this multi-agent call. + - `"program_output"` - `agent: optional object { agent_name }` @@ -165906,127 +164542,43 @@ 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"` + - `ToolSearchCall object { id, arguments, call_id, 5 more }` - - `"list_agents"` + - `id: string` - - `"send_message"` + The unique ID of the tool search call item. - - `"followup_task"` + - `arguments: unknown` - - `"wait_agent"` + Arguments used for the tool search call. - `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 array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` - - Citations associated with the text content. - - - `array of 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"` - - - `array of 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. - - - `array of 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. + The unique ID of the tool search call generated by the model. - - `filename: string` + - `execution: "server" or "client"` - The filename of the container file cited. + Whether tool search was executed by the server or by the client. - - `start_index: number` + - `"server"` - The index of the first character of the citation in the message. + - `"client"` - - `type: "container_file_citation"` + - `status: "in_progress" or "completed" or "incomplete"` - The citation type. Always `container_file_citation`. + The status of the tool search call item that was recorded. - - `"container_file_citation"` + - `"in_progress"` - - `type: "multi_agent_call_output"` + - `"completed"` - The item type. Always `multi_agent_call_output`. + - `"incomplete"` - - `"multi_agent_call_output"` + - `type: "tool_search_call"` - - `id: optional string` + The type of the item. Always `tool_search_call`. - The unique ID of this multi-agent call output. + - `"tool_search_call"` - `agent: optional object { agent_name }` @@ -166036,35 +164588,21 @@ 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 }` - - - `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. + - `created_by: optional string` - - `agent: optional object { agent_name }` + The identifier of the actor that created the item. - The agent that produced this item. + - `ToolSearchOutput object { id, call_id, execution, 5 more }` - - `agent_name: string` + - `id: string` - The canonical name of the agent that produced this item. + The unique ID of the tool search output item. - - `call_id: optional string` + - `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. @@ -166072,9 +164610,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"` @@ -166082,11 +164620,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 }` @@ -166349,7 +164885,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-web-search). + [web search tool](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -166409,7 +164945,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -166461,7 +164997,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -166607,40 +165143,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`. @@ -166685,19 +165189,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `background: optional "transparent" or "opaque" or "auto"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. - - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. - - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - `"transparent"` @@ -166726,13 +165219,13 @@ curl -X POST https://api.openai.com/v1/responses/compact \ Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `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-2" or 3 more` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` The image generation model to use. Default: `gpt-image-1`. @@ -166740,14 +165233,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"gpt-image-1-mini"` - - `"gpt-image-2"` - - - `"gpt-image-2-2026-04-21"` - - `"gpt-image-1.5"` - - `"chatgpt-image-latest"` - - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -166784,185 +165271,67 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"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` + - `"high"` - Base64-encoded skill zip bundle. + - `"auto"` - - `media_type: "application/zip"` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - The media type of the inline skill payload. Must be `application/zip`. + 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`. - - `"application/zip"` + - `string` - - `type: "base64"` + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - The type of the inline skill source. Must be `base64`. + 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`. - - `"base64"` + - `"1024x1024"` - - `type: "inline"` + - `"1024x1536"` - Defines an inline skill for this request. + - `"1536x1024"` - - `"inline"` + - `"auto"` - - `BetaLocalEnvironment object { type, skills }` + - `LocalShell object { type }` - - `type: "local"` + A tool that allows the model to execute shell commands in a local environment. - Use a local computer environment. + - `type: "local_shell"` - - `"local"` + The type of the local shell tool. Always `local_shell`. - - `skills: optional array of BetaLocalSkill` + - `"local_shell"` - An optional list of skills. + - `Shell object { type, allowed_callers, environment }` - - `description: string` + A tool that allows the model to execute shell commands. - The description of the skill. + - `type: "shell"` - - `name: string` + The type of the shell tool. Always `shell`. - The name of the skill. + - `"shell"` - - `path: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The path to the directory containing the skill. + The tool invocation context(s). - - `BetaContainerReference object { container_id, type }` + - `"direct"` - - `container_id: string` + - `"programmatic"` - The ID of the referenced container. + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - `type: "container_reference"` + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - References a container created with the /v1/containers endpoint + - `BetaLocalEnvironment object { type, skills }` - - `"container_reference"` + - `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](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -167076,7 +165445,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -167246,14 +165615,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. @@ -167262,39 +165627,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 }` @@ -167557,7 +165922,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-web-search). + [web search tool](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -167617,7 +165982,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -167669,7 +166034,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -167861,19 +166226,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `background: optional "transparent" or "opaque" or "auto"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. - - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. - - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - `"transparent"` @@ -167902,13 +166256,13 @@ curl -X POST https://api.openai.com/v1/responses/compact \ Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `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-2" or 3 more` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` The image generation model to use. Default: `gpt-image-1`. @@ -167916,14 +166270,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"gpt-image-1-mini"` - - `"gpt-image-2"` - - - `"gpt-image-2-2026-04-21"` - - `"gpt-image-1.5"` - - `"chatgpt-image-latest"` - - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -168020,7 +166368,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -168134,7 +166482,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -168304,14 +166652,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. @@ -168320,82 +166664,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](https://platform.openai.com/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 - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. - - - `status: optional "in_progress" or "completed" or "incomplete"` - - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `Compaction object { encrypted_content, type, id, agent }` - - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/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"` @@ -168403,10 +166682,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. @@ -168415,6 +166690,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. @@ -168632,1192 +166911,2080 @@ 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 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` + + 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 + + - `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. + + - `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` + + Exit code from the shell process. + + - `type: "exit"` + + The outcome type. Always `exit`. + + - `"exit"` + + - `stderr: string` + + The standard error output that was captured. + + - `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"` + + - `type: "shell_call_output"` + + The type of the shell call output. Always `shell_call_output`. + + - `"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"` + + - `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. + + - `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. - A tool representing a request to execute one or more shell commands. + - `BetaToolChoiceCustom object { name, type }` - - `action: object { commands, max_output_length, timeout_ms }` + Use this option to force the model to call a specific custom tool. - The shell commands and limits that describe how to run the tool call. + - `name: string` - - `commands: array of string` + The name of the custom tool to call. - Ordered shell commands for the execution environment to run. + - `type: "custom"` - - `max_output_length: optional number` + For custom tool calling, the type is always `custom`. - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + - `"custom"` - - `timeout_ms: optional number` + - `BetaSpecificProgrammaticToolCallingParam object { type }` - Maximum wall-clock time in milliseconds to allow the shell commands to run. + - `type: "programmatic_tool_calling"` - - `call_id: string` + The tool to call. Always `programmatic_tool_calling`. - The unique ID of the shell tool call generated by the model. + - `"programmatic_tool_calling"` - - `type: "shell_call"` + - `BetaToolChoiceApplyPatch object { type }` - The type of the item. Always `shell_call`. + Forces the model to call the apply_patch tool when executing a tool call. - - `"shell_call"` + - `type: "apply_patch"` - - `id: optional string` + The tool to call. Always `apply_patch`. - The unique ID of the shell tool call. Populated when this item is returned via API. + - `"apply_patch"` - - `agent: optional object { agent_name }` + - `BetaToolChoiceShell object { type }` - The agent that produced this item. + Forces the model to call the shell tool when a tool call is required. - - `agent_name: string` + - `type: "shell"` - The canonical name of the agent that produced this item. + The tool to call. Always `shell`. - - `caller: optional object { type } or object { caller_id, type }` + - `"shell"` - The execution context that produced this 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` - - `Direct object { 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. - - `type: "direct"` + We support the following categories of tools: - The caller type. Always `direct`. + - **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. - - `"direct"` + - `Function object { name, parameters, strict, 5 more }` - - `Program object { caller_id, 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). - - `caller_id: string` + - `name: string` - The call ID of the program item that produced this tool call. + The name of the function to call. - - `type: "program"` + - `parameters: map[unknown]` - The caller type. Always `program`. + A JSON schema object describing the parameters of the function. - - `"program"` + - `strict: boolean` - - `environment: optional BetaLocalEnvironment or BetaContainerReference` + Whether strict parameter validation is enforced for this function tool. - The environment to execute the shell commands in. + - `type: "function"` - - `BetaLocalEnvironment object { type, skills }` + The type of the function tool. Always `function`. - - `BetaContainerReference object { container_id, type }` + - `"function"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `allowed_callers: optional array of "direct" or "programmatic"` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + The tool invocation context(s). - - `"in_progress"` + - `"direct"` - - `"completed"` + - `"programmatic"` - - `"incomplete"` + - `defer_loading: optional boolean` - - `ShellCallOutput object { call_id, output, type, 5 more }` + Whether this function is deferred and loaded via tool search. - The streamed output items emitted by a shell tool call. + - `description: optional string` - - `call_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 shell tool call generated by the model. + - `output_schema: optional map[unknown]` - - `output: array of BetaResponseFunctionShellCallOutputContent` + A JSON schema object describing the JSON value encoded in string outputs for this function. - Captured chunks of stdout and stderr output, along with their associated outcomes. + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - - `outcome: object { type } or object { exit_code, 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). - The exit or timeout outcome associated with this shell call. + - `type: "file_search"` - - `Timeout object { type }` + The type of the file search tool. Always `file_search`. - Indicates that the shell call exceeded its configured time limit. + - `"file_search"` - - `type: "timeout"` + - `vector_store_ids: array of string` - The outcome type. Always `timeout`. + The IDs of the vector stores to search. - - `"timeout"` + - `filters: optional object { key, type, value } or object { filters, type }` - - `Exit object { exit_code, type }` + A filter to apply. - Indicates that the shell commands finished and returned an exit code. + - `ComparisonFilter object { key, type, value }` - - `exit_code: number` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The exit code returned by the shell process. + - `key: string` - - `type: "exit"` + The key to compare against the value. - The outcome type. Always `exit`. + - `type: "eq" or "ne" or "gt" or 5 more` - - `"exit"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `stderr: 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 - Captured stderr output for the shell call. + - `"eq"` - - `stdout: string` + - `"ne"` - Captured stdout output for the shell call. + - `"gt"` - - `type: "shell_call_output"` + - `"gte"` - The type of the item. Always `shell_call_output`. + - `"lt"` - - `"shell_call_output"` + - `"lte"` - - `id: optional string` + - `"in"` - The unique ID of the shell tool call output. Populated when this item is returned via API. + - `"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` - - `caller: optional object { type } or object { caller_id, type }` + - `boolean` - The execution context that produced this tool call. + - `array of string or number` - - `Direct object { type }` + - `string` - - `type: "direct"` + - `number` - The caller type. Always `direct`. + - `CompoundFilter object { filters, type }` - - `"direct"` + Combine multiple filters using `and` or `or`. - - `Program object { caller_id, type }` + - `filters: array of object { key, type, value } or unknown` - - `caller_id: string` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - The call ID of the program item that produced this tool call. + - `ComparisonFilter object { key, type, value }` - - `type: "program"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The caller type. Always `program`. + - `key: string` - - `"program"` + The key to compare against the value. - - `max_output_length: optional number` + - `type: "eq" or "ne" or "gt" or 5 more` - The maximum number of UTF-8 characters captured for this shell call's combined output. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `status: optional "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 shell call output. + - `"eq"` - - `"in_progress"` + - `"ne"` - - `"completed"` + - `"gt"` - - `"incomplete"` + - `"gte"` - - `ApplyPatchCall object { call_id, operation, status, 4 more }` + - `"lt"` - A tool call representing a request to create, delete, or update files using diff patches. + - `"lte"` - - `call_id: string` + - `"in"` - The unique ID of the apply patch tool call generated by the model. + - `"nin"` - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + - `value: string or number or boolean or array of string or number` - The specific create, delete, or update instruction for the apply_patch tool call. + The value to compare against the attribute key; supports string, number, or boolean types. - - `CreateFile object { diff, path, type }` + - `string` - Instruction for creating a new file via the apply_patch tool. + - `number` - - `diff: string` + - `boolean` - Unified diff content to apply when creating the file. + - `array of string or number` - - `path: string` + - `string` - Path of the file to create relative to the workspace root. + - `number` - - `type: "create_file"` + - `unknown` - The operation type. Always `create_file`. + - `type: "and" or "or"` - - `"create_file"` + Type of operation: `and` or `or`. - - `DeleteFile object { path, type }` + - `"and"` - Instruction for deleting an existing file via the apply_patch tool. + - `"or"` - - `path: string` + - `max_num_results: optional number` - Path of the file to delete relative to the workspace root. + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `type: "delete_file"` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - The operation type. Always `delete_file`. + Ranking options for search. - - `"delete_file"` + - `hybrid_search: optional object { embedding_weight, text_weight }` - - `UpdateFile object { diff, path, type }` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - Instruction for updating an existing file via the apply_patch tool. + - `embedding_weight: number` - - `diff: string` + The weight of the embedding in the reciprocal ranking fusion. - Unified diff content to apply to the existing file. + - `text_weight: number` - - `path: string` + The weight of the text in the reciprocal ranking fusion. - Path of the file to update relative to the workspace root. + - `ranker: optional "auto" or "default-2024-11-15"` - - `type: "update_file"` + The ranker to use for the file search. - The operation type. Always `update_file`. + - `"auto"` - - `"update_file"` + - `"default-2024-11-15"` - - `status: "in_progress" or "completed"` + - `score_threshold: optional number` - The status of the apply patch tool call. One of `in_progress` or `completed`. + 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). - - `type: "apply_patch_call"` + - `type: "computer"` - The type of the item. Always `apply_patch_call`. + The type of the computer tool. Always `computer`. - - `"apply_patch_call"` + - `"computer"` - - `id: optional string` + - `ComputerUsePreview object { display_height, display_width, environment, type }` - The unique ID of the apply patch 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). - - `ApplyPatchCallOutput object { call_id, status, type, 4 more }` + - `type: "web_search" or "web_search_2025_08_26"` - The streamed output emitted by an apply patch tool call. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `call_id: string` + - `"web_search"` - The unique ID of the apply patch tool call generated by the model. + - `"web_search_2025_08_26"` - - `status: "completed" or "failed"` + - `filters: optional object { allowed_domains }` - The status of the apply patch tool call output. One of `completed` or `failed`. + Filters for the search. - - `"completed"` + - `allowed_domains: optional array of string` - - `"failed"` + 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_output"` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - The type of the item. Always `apply_patch_call_output`. + - `search_context_size: optional "low" or "medium" or "high"` - - `"apply_patch_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 apply patch tool call output. Populated when this item is returned via API. + - `"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` - - `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` + - `type: optional "approximate"` - The call ID of the program item that produced this tool call. + The type of location approximation. Always `approximate`. - - `type: "program"` + - `"approximate"` - The caller type. Always `program`. + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `"program"` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - - `output: optional string` + - `server_label: string` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + A label for this MCP server, used to identify it in tool calls. - - `McpListTools object { id, server_label, tools, 3 more }` + - `type: "mcp"` - A list of tools available on an MCP server. + The type of the MCP tool. Always `mcp`. - - `id: string` + - `"mcp"` - The unique ID of the list. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `server_label: string` + The tool invocation context(s). - The label of the MCP server. + - `"direct"` - - `tools: array of object { input_schema, name, annotations, description }` + - `"programmatic"` - The tools available on the server. + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `input_schema: unknown` + List of allowed tool names or a filter object. - The JSON schema describing the tool's input. + - `McpAllowedTools = array of string` - - `name: string` + A string array of allowed tool names - The name of the tool. + - `McpToolFilter object { read_only, tool_names }` - - `annotations: optional unknown` + A filter object to specify which tools are allowed. - Additional annotations about the tool. + - `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. - The description of the tool. + - `tool_names: optional array of string` - - `type: "mcp_list_tools"` + List of allowed tool names. - The type of the item. Always `mcp_list_tools`. + - `authorization: optional string` - - `"mcp_list_tools"` + 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` - - `error: optional string` + - `"connector_dropbox"` - Error message if the server could not list tools. + - `"connector_gmail"` - - `McpApprovalRequest object { id, arguments, name, 3 more }` + - `"connector_googlecalendar"` - A request for human approval of a tool invocation. + - `"connector_googledrive"` - - `id: string` + - `"connector_microsoftteams"` - The unique ID of the approval request. + - `"connector_outlookcalendar"` - - `arguments: string` + - `"connector_outlookemail"` - A JSON string of arguments for the tool. + - `"connector_sharepoint"` - - `name: string` + - `defer_loading: optional boolean` - The name of the tool to run. + Whether this MCP tool is deferred and discovered via tool search. - - `server_label: string` + - `headers: optional map[string]` - The label of the MCP server making the request. + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `type: "mcp_approval_request"` + - `require_approval: optional object { always, never } or "always" or "never"` - The type of the item. Always `mcp_approval_request`. + Specify which of the MCP server's tools require approval. - - `"mcp_approval_request"` + - `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` - - `McpApprovalResponse object { approval_request_id, approve, type, 3 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 response to an MCP approval request. + - `tool_names: optional array of string` - - `approval_request_id: string` + List of allowed tool names. - The ID of the approval request being answered. + - `never: optional object { read_only, tool_names }` - - `approve: boolean` + A filter object to specify which tools are allowed. - Whether the request was approved. + - `read_only: optional boolean` - - `type: "mcp_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. - The type of the item. Always `mcp_approval_response`. + - `tool_names: optional array of string` - - `"mcp_approval_response"` + List of allowed tool names. - - `id: optional 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. - - `agent: optional object { agent_name }` + - `"always"` - The agent that produced this item. + - `"never"` - - `agent_name: string` + - `server_description: optional string` - The canonical name of the agent that produced this item. + Optional description of the MCP server, used to provide more context. - - `reason: optional string` + - `server_url: optional string` - Optional reason for the decision. + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `McpCall object { id, arguments, name, 7 more }` + - `tunnel_id: optional string` - An invocation of a tool on an MCP server. + 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 unique ID of the tool call. + A tool that runs Python code to help generate a response to a prompt. - - `arguments: string` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - A JSON string of the arguments passed to the 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. - - `name: string` + - `string` - The name of the tool that was run. + The container ID. - - `server_label: string` + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - The label of the MCP server running the tool. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `type: "mcp_call"` + - `type: "auto"` - The type of the item. Always `mcp_call`. + Always `auto`. - - `"mcp_call"` + - `"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. - - `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"` + - `type: "code_interpreter"` - - `"completed"` + The type of the code interpreter tool. Always `code_interpreter`. - - `"incomplete"` + - `"code_interpreter"` - - `"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` + - `ProgrammaticToolCalling object { type }` - The call ID, used to map this custom tool call output to a custom tool call. + - `type: "programmatic_tool_calling"` - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + The type of the tool. Always `programmatic_tool_calling`. - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `"programmatic_tool_calling"` - - `StringOutput = string` + - `ImageGeneration object { type, action, background, 9 more }` - A string of the output of the custom tool call. + A tool that generates images using the GPT image models. - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `type: "image_generation"` - Text, image, or file output of the custom tool call. + The type of the image generation tool. Always `image_generation`. - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `"image_generation"` - A text input to the model. + - `action: optional "generate" or "edit" or "auto"` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + Whether to generate a new image or edit an existing image. Default: `auto`. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `"generate"` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `"edit"` - A file input to the model. + - `"auto"` - - `type: "custom_tool_call_output"` + - `background: optional "transparent" or "opaque" or "auto"` - The type of the custom tool call output. Always `custom_tool_call_output`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - - `"custom_tool_call_output"` + - `"transparent"` - - `id: optional string` + - `"opaque"` - The unique ID of the custom tool call output in the OpenAI platform. + - `"auto"` - - `agent: optional object { agent_name }` + - `input_fidelity: optional "high" or "low"` - 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`. - - `agent_name: string` + - `"high"` - The canonical name of the agent that produced this item. + - `"low"` - - `caller: optional object { type } or object { caller_id, type }` + - `input_image_mask: optional object { file_id, image_url }` - The execution context that produced this tool call. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `Direct object { type }` + - `file_id: optional string` - - `type: "direct"` + File ID for the mask image. - The caller type. Always `direct`. + - `image_url: optional string` - - `"direct"` + Base64-encoded mask image. - - `Program object { caller_id, type }` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `caller_id: string` + The image generation model to use. Default: `gpt-image-1`. - The call ID of the program item that produced this tool call. + - `string` - - `type: "program"` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - The caller type. Always `program`. + The image generation model to use. Default: `gpt-image-1`. - - `"program"` + - `"gpt-image-1"` - - `CustomToolCall object { call_id, input, name, 5 more }` + - `"gpt-image-1-mini"` - A call to a custom tool created by the model. + - `"gpt-image-1.5"` - - `call_id: string` + - `moderation: optional "auto" or "low"` - An identifier used to map this custom tool call to a tool call output. + Moderation level for the generated image. Default: `auto`. - - `input: string` + - `"auto"` - The input for the custom tool call generated by the model. + - `"low"` - - `name: string` + - `output_compression: optional number` - The name of the custom tool being called. + Compression level for the output image. Default: 100. - - `type: "custom_tool_call"` + - `output_format: optional "png" or "webp" or "jpeg"` - The type of the custom tool call. Always `custom_tool_call`. + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `"custom_tool_call"` + - `"png"` - - `id: optional string` + - `"webp"` - The unique ID of the custom tool call in the OpenAI platform. + - `"jpeg"` - - `agent: optional object { agent_name }` + - `partial_images: optional number` - The agent that produced this item. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `agent_name: string` + - `quality: optional "low" or "medium" or "high" or "auto"` - The canonical name of the agent that produced this item. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `caller: optional object { type } or object { caller_id, type }` + - `"low"` - The execution context that produced this tool call. + - `"medium"` - - `Direct object { type }` + - `"high"` - - `type: "direct"` + - `"auto"` - - `"direct"` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `Program object { caller_id, type }` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `caller_id: string` + - `string` - The call ID of the program item that produced this tool call. + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `type: "program"` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `"program"` + - `"1024x1024"` - - `namespace: optional string` + - `"1024x1536"` - The namespace of the custom tool being called. + - `"1536x1024"` - - `CompactionTrigger object { type, agent }` + - `"auto"` - Compacts the current context. Must be the final input item. + - `LocalShell object { type }` - - `type: "compaction_trigger"` + A tool that allows the model to execute shell commands in a local environment. - The type of the item. Always `compaction_trigger`. + - `type: "local_shell"` - - `"compaction_trigger"` + 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"` - - `ItemReference object { id, agent, type }` + The type of the shell tool. Always `shell`. - An internal identifier for an item to reference. + - `"shell"` - - `id: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The ID of the item to reference. + 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 }` - - `type: optional "item_reference"` + - `BetaLocalEnvironment object { type, skills }` - The type of item to reference. Always `item_reference`. + - `BetaContainerReference object { container_id, type }` - - `"item_reference"` + - `Custom object { name, type, allowed_callers, 3 more }` - - `Program object { id, call_id, code, 3 more }` + 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 this program item. + The name of the custom tool, used to identify it in tool calls. - - `call_id: string` + - `type: "custom"` - The stable call ID of the program item. + The type of the custom tool. Always `custom`. - - `code: string` + - `"custom"` - The JavaScript source executed by programmatic tool calling. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `fingerprint: string` + The tool invocation context(s). - Opaque program replay fingerprint that must be round-tripped. + - `"direct"` - - `type: "program"` + - `"programmatic"` - The item type. Always `program`. + - `defer_loading: optional boolean` - - `"program"` + Whether this tool should be deferred and discovered via tool search. - - `agent: optional object { agent_name }` + - `description: optional string` - The agent that produced this item. + 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. - - `ProgramOutput object { id, call_id, result, 3 more }` + - `Text object { type }` - - `id: string` + Unconstrained free-form text. - The unique ID of this program output item. + - `type: "text"` - - `call_id: string` + Unconstrained text format. Always `text`. - The call ID of the program item. + - `"text"` - - `result: string` + - `Grammar object { definition, syntax, type }` - The result produced by the program item. + A grammar defined by the user. - - `status: "completed" or "incomplete"` + - `definition: string` - The terminal status of the program output. + The grammar definition. - - `"completed"` + - `syntax: "lark" or "regex"` - - `"incomplete"` + The syntax of the grammar definition. One of `lark` or `regex`. - - `type: "program_output"` + - `"lark"` - The item type. Always `program_output`. + - `"regex"` - - `"program_output"` + - `type: "grammar"` - - `agent: optional object { agent_name }` + Grammar format. Always `grammar`. - The agent that produced this item. + - `"grammar"` - - `agent_name: string` + - `Namespace object { description, name, tools, type }` - The canonical name of the agent that produced this item. + Groups function/custom tools under a shared namespace. - - `metadata: map[string]` + - `description: 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. + A description of the namespace shown to the model. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `name: string` - - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` + The namespace name used in tool calls (for example, `crm`). - 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](https://platform.openai.com/docs/models) - to browse and compare available models. + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - - `"gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more` + The function/custom tools available inside this namespace. - 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](https://platform.openai.com/docs/models) - to browse and compare available models. + - `Function object { name, type, allowed_callers, 5 more }` - - `"gpt-5.6-sol"` + - `name: string` - - `"gpt-5.6-terra"` + - `type: "function"` - - `"gpt-5.6-luna"` + - `"function"` - - `"gpt-5.4"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"gpt-5.4-mini"` + The tool invocation context(s). - - `"gpt-5.4-nano"` + - `"direct"` - - `"gpt-5.4-mini-2026-03-17"` + - `"programmatic"` - - `"gpt-5.4-nano-2026-03-17"` + - `defer_loading: optional boolean` - - `"gpt-5.3-chat-latest"` + Whether this function should be deferred and discovered via tool search. - - `"gpt-5.2"` + - `description: optional string` - - `"gpt-5.2-2025-12-11"` + - `output_schema: optional map[unknown]` - - `"gpt-5.2-chat-latest"` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `"gpt-5.2-pro"` + - `parameters: optional unknown` - - `"gpt-5.2-pro-2025-12-11"` + - `strict: optional boolean` - - `"gpt-5.1"` + 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. - - `"gpt-5.1-2025-11-13"` + - `Custom object { name, type, allowed_callers, 3 more }` - - `"gpt-5.1-codex"` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `"gpt-5.1-mini"` + - `name: string` - - `"gpt-5.1-chat-latest"` + The name of the custom tool, used to identify it in tool calls. - - `"gpt-5"` + - `type: "custom"` - - `"gpt-5-mini"` + The type of the custom tool. Always `custom`. - - `"gpt-5-nano"` + - `"custom"` - - `"gpt-5-2025-08-07"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"gpt-5-mini-2025-08-07"` + The tool invocation context(s). - - `"gpt-5-nano-2025-08-07"` + - `"direct"` - - `"gpt-5-chat-latest"` + - `"programmatic"` - - `"gpt-4.1"` + - `defer_loading: optional boolean` - - `"gpt-4.1-mini"` + Whether this tool should be deferred and discovered via tool search. - - `"gpt-4.1-nano"` + - `description: optional string` - - `"gpt-4.1-2025-04-14"` + Optional description of the custom tool, used to provide more context. - - `"gpt-4.1-mini-2025-04-14"` + - `format: optional object { type } or object { definition, syntax, type }` - - `"gpt-4.1-nano-2025-04-14"` + The input format for the custom tool. Default is unconstrained text. - - `"o4-mini"` + - `Text object { type }` - - `"o4-mini-2025-04-16"` + Unconstrained free-form text. - - `"o3"` + - `type: "text"` - - `"o3-2025-04-16"` + Unconstrained text format. Always `text`. - - `"o3-mini"` + - `"text"` - - `"o3-mini-2025-01-31"` + - `Grammar object { definition, syntax, type }` - - `"o1"` + A grammar defined by the user. - - `"o1-2024-12-17"` + - `definition: string` - - `"o1-preview"` + The grammar definition. - - `"o1-preview-2024-09-12"` + - `syntax: "lark" or "regex"` - - `"o1-mini"` + The syntax of the grammar definition. One of `lark` or `regex`. - - `"o1-mini-2024-09-12"` + - `"lark"` - - `"gpt-4o"` + - `"regex"` - - `"gpt-4o-2024-11-20"` + - `type: "grammar"` - - `"gpt-4o-2024-08-06"` + Grammar format. Always `grammar`. - - `"gpt-4o-2024-05-13"` + - `"grammar"` - - `"gpt-4o-audio-preview"` + - `type: "namespace"` - - `"gpt-4o-audio-preview-2024-10-01"` + The type of the tool. Always `namespace`. - - `"gpt-4o-audio-preview-2024-12-17"` + - `"namespace"` - - `"gpt-4o-audio-preview-2025-06-03"` + - `ToolSearch object { type, description, execution, parameters }` - - `"gpt-4o-mini-audio-preview"` + Hosted or BYOT tool search configuration for deferred tools. - - `"gpt-4o-mini-audio-preview-2024-12-17"` + - `type: "tool_search"` - - `"gpt-4o-search-preview"` + The type of the tool. Always `tool_search`. - - `"gpt-4o-mini-search-preview"` + - `"tool_search"` - - `"gpt-4o-search-preview-2025-03-11"` + - `description: optional string` - - `"gpt-4o-mini-search-preview-2025-03-11"` + Description shown to the model for a client-executed tool search tool. - - `"chatgpt-4o-latest"` + - `execution: optional "server" or "client"` - - `"codex-mini-latest"` + Whether tool search is executed by the server or by the client. - - `"gpt-4o-mini"` + - `"server"` - - `"gpt-4o-mini-2024-07-18"` + - `"client"` - - `"gpt-4-turbo"` + - `parameters: optional unknown` - - `"gpt-4-turbo-2024-04-09"` + Parameter schema for a client-executed tool search tool. - - `"gpt-4-0125-preview"` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - - `"gpt-4-turbo-preview"` + 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). - - `"gpt-4-1106-preview"` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `"gpt-4-vision-preview"` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `"gpt-4"` + - `"web_search_preview"` - - `"gpt-4-0314"` + - `"web_search_preview_2025_03_11"` - - `"gpt-4-0613"` + - `search_content_types: optional array of "text" or "image"` - - `"gpt-4-32k"` + - `"text"` - - `"gpt-4-32k-0314"` + - `"image"` - - `"gpt-4-32k-0613"` + - `search_context_size: optional "low" or "medium" or "high"` - - `"gpt-3.5-turbo"` + 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-3.5-turbo-16k"` + - `"low"` - - `"gpt-3.5-turbo-0301"` + - `"medium"` - - `"gpt-3.5-turbo-0613"` + - `"high"` - - `"gpt-3.5-turbo-1106"` + - `user_location: optional object { type, city, country, 2 more }` - - `"gpt-3.5-turbo-0125"` + The user's location. - - `"gpt-3.5-turbo-16k-0613"` + - `type: "approximate"` - - `"o1-pro"` + The type of location approximation. Always `approximate`. - - `"o1-pro-2025-03-19"` + - `"approximate"` - - `"o3-pro"` + - `city: optional string` - - `"o3-pro-2025-06-10"` + Free text input for the city of the user, e.g. `San Francisco`. - - `"o3-deep-research"` + - `country: optional string` - - `"o3-deep-research-2025-06-26"` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `"o4-mini-deep-research"` + - `region: optional string` - - `"o4-mini-deep-research-2025-06-26"` + Free text input for the region of the user, e.g. `California`. - - `"computer-use-preview"` + - `timezone: optional string` - - `"computer-use-preview-2025-03-11"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `"gpt-5-codex"` + - `ApplyPatch object { type, allowed_callers }` - - `"gpt-5-pro"` + Allows the assistant to create, delete, or update files using unified diffs. - - `"gpt-5-pro-2025-10-06"` + - `type: "apply_patch"` - - `"gpt-5.1-codex-max"` + The type of the tool. Always `apply_patch`. - - `string` + - `"apply_patch"` - - `object: "response"` + - `allowed_callers: optional array of "direct" or "programmatic"` - The object type of this resource - always set to `response`. + The tool invocation context(s). - - `"response"` + - `"direct"` - - `output: array of BetaResponseOutputItem` + - `"programmatic"` - An array of content items generated by the model. + - `top_p: 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. + 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. - - `BetaResponseOutputMessage object { id, content, role, 4 more }` + We generally recommend altering this or `temperature` but not both. - An output message from the model. + - `background: optional boolean` - - `FileSearchCall object { id, queries, status, 3 more }` + Whether to run the model response in the background. + [Learn more](/docs/guides/background). - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `completed_at: optional number` - - `id: string` + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - The unique ID of the file search tool call. + - `conversation: optional object { id }` - - `queries: array of string` + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - The queries used to search for files. + - `id: string` - - `status: "in_progress" or "searching" or "completed" or 2 more` + The unique ID of the conversation that this response was associated with. - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `max_output_tokens: optional number` - - `"in_progress"` + 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). - - `"searching"` + - `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 }` - - `"failed"` + Moderation results for the response input and output, if moderated completions were requested. - - `type: "file_search_call"` + - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` - The type of the file search tool call. Always `file_search_call`. + Moderation for the response input. - - `"file_search_call"` + - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` - - `agent: optional object { agent_name }` + A moderation result produced for the response input or output. - The agent that produced this item. + - `categories: map[boolean]` - - `agent_name: string` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - The canonical name of the agent that produced this item. + - `category_applied_input_types: map[array of "text" or "image"]` - - `results: optional array of object { attributes, file_id, filename, 2 more }` + Which modalities of input are reflected by the score for each category. - The results of the file search tool call. + - `"text"` - - `attributes: optional map[string or number or boolean]` + - `"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. + - `category_scores: map[number]` - - `string` + A dictionary of moderation categories to scores. - - `number` + - `flagged: boolean` - - `boolean` + A boolean indicating whether the content was flagged by any category. - - `file_id: optional string` + - `model: string` - The unique ID of the file. + The moderation model that produced this result. - - `filename: optional string` + - `type: "moderation_result"` - The name of the file. + The object type, which was always `moderation_result` for successful moderation results. - - `score: optional number` + - `"moderation_result"` - The relevance score of the file - a value between 0 and 1. + - `Error object { code, message, type }` - - `text: optional string` + An error produced while attempting moderation for the response input or output. - The text that was retrieved from the file. + - `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](https://platform.openai.com/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: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` - The name of the function to run. + Moderation for the response output. - - `type: "function_call"` + - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` - The type of the function tool call. Always `function_call`. + A moderation result produced for the response input or output. - - `"function_call"` + - `categories: map[boolean]` - - `id: optional string` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - The unique ID of the function tool call. + - `category_applied_input_types: map[array of "text" or "image"]` - - `agent: optional object { agent_name }` + Which modalities of input are reflected by the score for each category. - The agent that produced this item. + - `"text"` - - `agent_name: string` + - `"image"` - The canonical name of the agent that produced this item. + - `category_scores: map[number]` - - `caller: optional object { type } or object { caller_id, type }` + A dictionary of moderation categories to scores. - The execution context that produced this tool call. + - `flagged: boolean` - - `Direct object { type }` + A boolean indicating whether the content was flagged by any category. - - `type: "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 }` - - `"program"` + An error produced while attempting moderation for the response input or output. - - `namespace: optional string` + - `code: string` - The namespace of the function to run. + The error code. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `message: string` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The error message. - - `"in_progress"` + - `type: "error"` - - `"completed"` + The object type, which was always `error` for moderation failures. - - `"incomplete"` + - `"error"` - - `FunctionCallOutput object { id, call_id, output, 5 more }` + - `output_text: optional string` - - `id: 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 unique ID of the function call tool output. + - `previous_response_id: optional string` - - `call_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 function tool call generated by the model. + - `prompt: optional BetaResponsePrompt` - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + Reference to a prompt template and its variables. + [Learn more](/docs/guides/text?api-mode=responses#reusable-prompts). - The output from the function call generated by your code. - Can be a string or an list of output content. + - `id: string` - - `StringOutput = string` + The unique identifier of the prompt template to use. - A string of the output of the function call. + - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` - - `OutputContentList = array of 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. - Text, image, or file output of the function call. + - `string` - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` @@ -169825,2850 +168992,2859 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + 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"` + - `version: optional string` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Optional version of the prompt template. - - `"in_progress"` + - `prompt_cache_key: optional string` - - `"completed"` + 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). - - `"incomplete"` + - `prompt_cache_options: optional object { mode, ttl }` - - `type: "function_call_output"` + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - The type of the function tool call output. Always `function_call_output`. + - `mode: "implicit" or "explicit"` - - `"function_call_output"` + Whether implicit prompt-cache breakpoints were enabled. - - `agent: optional object { agent_name }` + - `"implicit"` - The agent that produced this item. + - `"explicit"` - - `agent_name: string` + - `ttl: "30m"` - The canonical name of the agent that produced this item. + The minimum lifetime applied to each cache breakpoint. - - `caller: optional object { type } or object { caller_id, type }` + - `"30m"` - The execution context that produced this tool call. + - `prompt_cache_retention: optional "in_memory" or "24h"` - - `Direct object { type }` + Deprecated. Use `prompt_cache_options.ttl` instead. - - `type: "direct"` + 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 caller type. Always `direct`. + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - - `"direct"` + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - - `Program object { caller_id, type }` + - `"in_memory"` - - `caller_id: string` + - `"24h"` - The call ID of the program item that produced this tool call. + - `reasoning: optional object { context, effort, generate_summary, 2 more }` - - `type: "program"` + **gpt-5 and o-series models only** - The caller type. Always `program`. + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - `"program"` + - `context: optional "auto" or "current_turn" or "all_turns"` - - `created_by: optional string` + Controls which reasoning items are rendered back to the model on later turns. + When returned on a response, this is the effective reasoning context mode + used for the response. - The identifier of the actor that created the item. + - `"auto"` - - `AgentMessage object { id, author, content, 3 more }` + - `"current_turn"` - - `id: string` + - `"all_turns"` - The unique ID of the agent message. + - `effort: optional "none" or "minimal" or "low" or 4 more` - - `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 BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` + - `"minimal"` - Encrypted content sent between agents. + - `"low"` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `"medium"` - A text input to the model. + - `"high"` - - `BetaResponseOutputText object { annotations, text, type, logprobs }` + - `"xhigh"` - A text output from the model. + - `"max"` - - `Text object { text, type }` + - `generate_summary: optional "auto" or "concise" or "detailed"` - A text content. + **Deprecated:** use `summary` instead. - - `text: 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`. - - `type: "text"` + - `"auto"` - - `"text"` + - `"concise"` - - `SummaryText object { text, type }` + - `"detailed"` - A summary text from the model. + - `mode: optional string or "standard" or "pro"` - - `text: string` + Controls the reasoning execution mode for the request. - A summary of the reasoning output from the model so far. + When returned on a response, this is the effective execution mode. - - `type: "summary_text"` + - `string` - The type of the object. Always `summary_text`. + - `"standard" or "pro"` - - `"summary_text"` + Controls the reasoning execution mode for the request. - - `ReasoningText object { text, type }` + When returned on a response, this is the effective execution mode. - Reasoning text from the model. + - `"standard"` - - `text: string` + - `"pro"` - The reasoning text from the model. + - `summary: optional "auto" or "concise" or "detailed"` - - `type: "reasoning_text"` + 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 type of the reasoning text. Always `reasoning_text`. + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - - `"reasoning_text"` + - `"auto"` - - `BetaResponseOutputRefusal object { refusal, type }` + - `"concise"` - A refusal from the model. + - `"detailed"` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `safety_identifier: optional string` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + 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). - - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` + - `service_tier: optional "auto" or "default" or "flex" or 2 more` - A screenshot of a computer. + Specifies the processing type used for serving the request. - - `detail: "low" or "high" or "auto" or "original"` + - 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 detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `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. - - `"low"` + - `"auto"` - - `"high"` + - `"default"` - - `"auto"` + - `"flex"` - - `"original"` + - `"scale"` - - `file_id: string` + - `"priority"` - The identifier of an uploaded file that contains the screenshot. + - `status: optional BetaResponseStatus` - - `image_url: string` + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - The URL of the screenshot image. + - `"completed"` - - `type: "computer_screenshot"` + - `"failed"` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + - `"in_progress"` - - `"computer_screenshot"` + - `"cancelled"` - - `prompt_cache_breakpoint: optional object { mode }` + - `"queued"` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `"incomplete"` - - `mode: "explicit"` + - `text: optional BetaResponseTextConfig` - The breakpoint mode. Always `explicit`. + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - - `"explicit"` + - [Text inputs and outputs](/docs/guides/text) + - [Structured Outputs](/docs/guides/structured-outputs) - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `format: optional BetaResponseFormatTextConfig` - A file input to the model. + An object specifying the format that the model must output. - - `EncryptedContent object { encrypted_content, 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). - Opaque encrypted content that Responses API decrypts inside trusted model execution. + The default format is `{ "type": "text" }` with no additional options. - - `encrypted_content: string` + **Not recommended for gpt-4o and newer models:** - Opaque encrypted content. + 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. - - `type: "encrypted_content"` + - `Text object { type }` - The type of the input item. Always `encrypted_content`. + Default response format. Used to generate text responses. - - `"encrypted_content"` + - `type: "text"` - - `recipient: string` + The type of response format being defined. Always `text`. - The destination agent identity. + - `"text"` - - `type: "agent_message"` + - `BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` - The type of the item. Always `agent_message`. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - - `"agent_message"` + - `name: string` - - `agent: optional object { agent_name }` + 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 agent that produced this item. + - `schema: map[unknown]` - - `agent_name: 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 canonical name of the agent that produced this item. + - `type: "json_schema"` - - `MultiAgentCall object { id, action, arguments, 3 more }` + The type of response format being defined. Always `json_schema`. - - `id: string` + - `"json_schema"` - The unique ID of the multi-agent call item. + - `description: optional string` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + A description of what the response format is for, used by the model to + determine how to respond in the format. - The multi-agent action to execute. + - `strict: optional boolean` - - `"spawn_agent"` + 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). - - `"interrupt_agent"` + - `JSONObject object { type }` - - `"list_agents"` + 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. - - `"send_message"` + - `type: "json_object"` - - `"followup_task"` + The type of response format being defined. Always `json_object`. - - `"wait_agent"` + - `"json_object"` - - `arguments: string` + - `verbosity: optional "low" or "medium" or "high"` - The JSON string of arguments generated for the action. + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. - - `call_id: string` + - `"low"` - The unique ID linking this call to its output. + - `"medium"` - - `type: "multi_agent_call"` + - `"high"` - The type of the multi-agent call. Always `multi_agent_call`. + - `top_logprobs: optional number` - - `"multi_agent_call"` + 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: optional object { agent_name }` + - `truncation: optional "auto" or "disabled"` - The agent that produced this item. + The truncation strategy to use for the model response. - - `agent_name: 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 canonical name of the agent that produced this item. + - `"auto"` - - `MultiAgentCallOutput object { id, action, call_id, 3 more }` + - `"disabled"` - - `id: string` + - `usage: optional BetaResponseUsage` - The unique ID of the multi-agent call output item. + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `input_tokens: number` - The multi-agent action that produced this result. + The number of input tokens. - - `"spawn_agent"` + - `input_tokens_details: object { cache_write_tokens, cached_tokens }` - - `"interrupt_agent"` + A detailed breakdown of the input tokens. - - `"list_agents"` + - `cache_write_tokens: number` - - `"send_message"` + The number of input tokens that were written to the cache. - - `"followup_task"` + - `cached_tokens: number` - - `"wait_agent"` + The number of tokens that were retrieved from the cache. + [More on prompt caching](/docs/guides/prompt-caching). - - `call_id: string` + - `output_tokens: number` - The unique ID of the multi-agent call. + The number of output tokens. - - `output: array of BetaResponseOutputText` + - `output_tokens_details: object { reasoning_tokens }` - Text output returned by the multi-agent action. + A detailed breakdown of the output tokens. - - `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 }` + - `reasoning_tokens: number` - The annotations of the text output. + The number of reasoning tokens. - - `text: string` + - `total_tokens: number` - The text output from the model. + The total number of tokens used. - - `type: "output_text"` + - `user: optional string` - The type of the output text. Always `output_text`. + 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). - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + - `sequence_number: number` - - `type: "multi_agent_call_output"` + The sequence number for this event. - The type of the multi-agent result. Always `multi_agent_call_output`. + - `type: "response.completed"` - - `"multi_agent_call_output"` + The type of the event. Always `response.completed`. + + - `"response.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. - - `WebSearchCall object { id, action, status, 2 more }` + - `BetaResponseContentPartAddedEvent object { content_index, item_id, output_index, 4 more }` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + Emitted when a new content part is added. - - `id: string` + - `content_index: number` - The unique ID of the web search tool call. + The index of the content part that was added. - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + - `item_id: 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). + The ID of the output item that the content part was added to. - - `Search object { type, queries, query, sources }` + - `output_index: number` - Action type "search" - Performs a web search query. + The index of the output item that the content part was added to. - - `type: "search"` + - `part: BetaResponseOutputText or BetaResponseOutputRefusal or object { text, type }` - The action type. + The content part that was added. - - `"search"` + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - - `queries: optional array of string` + A text output from the model. - The search queries. + - `BetaResponseOutputRefusal object { refusal, type }` - - `query: optional string` + A refusal from the model. - The search query. + - `ReasoningText object { text, type }` - - `sources: optional array of object { type, url }` + Reasoning text from the model. - The sources used in the search. + - `text: string` - - `type: "url"` + The reasoning text from the model. - The type of source. Always `url`. + - `type: "reasoning_text"` - - `"url"` + The type of the reasoning text. Always `reasoning_text`. - - `url: string` + - `"reasoning_text"` - The URL of the source. + - `sequence_number: number` - - `OpenPage object { type, url }` + The sequence number of this event. - Action type "open_page" - Opens a specific URL from search results. + - `type: "response.content_part.added"` - - `type: "open_page"` + The type of the event. Always `response.content_part.added`. - The action type. + - `"response.content_part.added"` - - `"open_page"` + - `agent: optional object { agent_name }` - - `url: optional string` + The agent that owns this multi-agent streaming event. - The URL opened by the model. + - `agent_name: string` - - `FindInPage object { pattern, type, url }` + The canonical name of the agent that produced this item. - Action type "find_in_page": Searches for a pattern within a loaded page. + - `BetaResponseContentPartDoneEvent object { content_index, item_id, output_index, 4 more }` - - `pattern: string` + Emitted when a content part is done. - The pattern or text to search for within the page. + - `content_index: number` - - `type: "find_in_page"` + The index of the content part that is done. - The action type. + - `item_id: string` - - `"find_in_page"` + The ID of the output item that the content part was added to. - - `url: string` + - `output_index: number` - The URL of the page searched for the pattern. + The index of the output item that the content part was added to. - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `part: BetaResponseOutputText or BetaResponseOutputRefusal or object { text, type }` - The status of the web search tool call. + The content part that is done. - - `"in_progress"` + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - - `"searching"` + A text output from the model. - - `"completed"` + - `BetaResponseOutputRefusal object { refusal, type }` - - `"failed"` + A refusal from the model. - - `type: "web_search_call"` + - `ReasoningText object { text, type }` - The type of the web search tool call. Always `web_search_call`. + Reasoning text from the model. - - `"web_search_call"` + - `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.content_part.done"` + + The type of the event. Always `response.content_part.done`. + + - `"response.content_part.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. - - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` + - `BetaResponseCreatedEvent object { response, sequence_number, type, agent }` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + An event that is emitted when a response is created. - - `id: string` + - `response: BetaResponse` - The unique ID of the computer call. + The response that was created. - - `call_id: string` + - `sequence_number: number` - An identifier used when responding to the tool call with output. + The sequence number for this event. - - `pending_safety_checks: array of object { id, code, message }` + - `type: "response.created"` - The pending safety checks for the computer call. + The type of the event. Always `response.created`. - - `id: string` + - `"response.created"` - The ID of the pending safety check. + - `agent: optional object { agent_name }` - - `code: optional string` + The agent that owns this multi-agent streaming event. - The type of the pending safety check. + - `agent_name: string` - - `message: optional string` + The canonical name of the agent that produced this item. - Details about the pending safety check. + - `BetaResponseErrorEvent object { code, message, param, 3 more }` - - `status: "in_progress" or "completed" or "incomplete"` + Emitted when an error occurs. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `code: string` - - `"in_progress"` + The error code. - - `"completed"` + - `message: string` - - `"incomplete"` + The error message. - - `type: "computer_call"` + - `param: string` - The type of the computer call. Always `computer_call`. + The error parameter. - - `"computer_call"` + - `sequence_number: number` - - `action: optional BetaComputerAction` + The sequence number of this event. - A click action. + - `type: "error"` - - `actions: optional BetaComputerActionList` + The type of the event. Always `error`. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `"error"` - `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 { id, call_id, output, 5 more }` + - `BetaResponseFileSearchCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` - - `id: string` + Emitted when a file search call is completed (results found). - The unique ID of the computer call tool output. + - `item_id: string` - - `call_id: string` + The ID of the output item that the file search call is initiated. - The ID of the computer tool call that produced the output. + - `output_index: number` - - `output: BetaResponseComputerToolCallOutputScreenshot` + The index of the output item that the file search call is initiated. - A computer screenshot image used with the computer use tool. + - `sequence_number: number` - - `status: "completed" or "incomplete" or "failed" or "in_progress"` + The sequence number of this event. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `type: "response.file_search_call.completed"` - - `"completed"` + The type of the event. Always `response.file_search_call.completed`. - - `"incomplete"` + - `"response.file_search_call.completed"` - - `"failed"` + - `agent: optional object { agent_name }` - - `"in_progress"` + The agent that owns this multi-agent streaming event. - - `type: "computer_call_output"` + - `agent_name: string` - The type of the computer tool call output. Always `computer_call_output`. + The canonical name of the agent that produced this item. - - `"computer_call_output"` + - `BetaResponseFileSearchCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` - - `acknowledged_safety_checks: optional array of object { id, code, message }` + Emitted when a file search call is initiated. - The safety checks reported by the API that have been acknowledged by the - developer. + - `item_id: string` - - `id: string` + The ID of the output item that the file search call is initiated. - The ID of the pending safety check. + - `output_index: number` - - `code: optional string` + The index of the output item that the file search call is initiated. - The type of the pending safety check. + - `sequence_number: number` - - `message: optional string` + The sequence number of this event. - Details about the pending safety check. + - `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 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. - - - `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](https://platform.openai.com/docs/guides/conversation-state). - - - `id: string` - - The unique identifier of the reasoning content. + - `BetaResponseFileSearchCallSearchingEvent object { item_id, output_index, sequence_number, 2 more }` - - `summary: array of object { text, type }` + Emitted when a file search is currently searching. - Reasoning summary content. + - `item_id: string` - - `text: string` + The ID of the output item that the file search call is initiated. - A summary of the reasoning output from the model so far. + - `output_index: number` - - `type: "summary_text"` + The index of the output item that the file search call is searching. - The type of the object. Always `summary_text`. + - `sequence_number: number` - - `"summary_text"` + The sequence number of this event. - - `type: "reasoning"` + - `type: "response.file_search_call.searching"` - The type of the object. Always `reasoning`. + The type of the event. Always `response.file_search_call.searching`. - - `"reasoning"` + - `"response.file_search_call.searching"` - `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. - - `content: optional array of object { text, type }` + - `BetaResponseFunctionCallArgumentsDeltaEvent object { delta, item_id, output_index, 3 more }` - Reasoning text content. + Emitted when there is a partial function-call arguments delta. - - `text: string` + - `delta: string` - The reasoning text from the model. + The function-call arguments delta that is added. - - `type: "reasoning_text"` + - `item_id: string` - The type of the reasoning text. Always `reasoning_text`. + The ID of the output item that the function-call arguments delta is added to. - - `"reasoning_text"` + - `output_index: number` - - `encrypted_content: optional string` + The index of the output item that the function-call arguments delta is added to. - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `sequence_number: number` - - `status: optional "in_progress" or "completed" or "incomplete"` + The sequence number of this event. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `type: "response.function_call_arguments.delta"` - - `"in_progress"` + The type of the event. Always `response.function_call_arguments.delta`. - - `"completed"` + - `"response.function_call_arguments.delta"` - - `"incomplete"` + - `agent: optional object { agent_name }` - - `Program object { id, call_id, code, 3 more }` + The agent that owns this multi-agent streaming event. - - `id: string` + - `agent_name: string` - The unique ID of the program item. + The canonical name of the agent that produced this item. - - `call_id: string` + - `BetaResponseFunctionCallArgumentsDoneEvent object { arguments, item_id, name, 4 more }` - The stable call ID of the program item. + Emitted when function-call arguments are finalized. - - `code: string` + - `arguments: string` - The JavaScript source executed by programmatic tool calling. + The function-call arguments. - - `fingerprint: string` + - `item_id: string` - Opaque program replay fingerprint that must be round-tripped. + The ID of the item. - - `type: "program"` + - `name: string` - The type of the item. Always `program`. + The name of the function that was called. - - `"program"` + - `output_index: number` - - `agent: optional object { agent_name }` + The index of the output item. - 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. + - `type: "response.function_call_arguments.done"` - - `ProgramOutput object { id, call_id, result, 3 more }` + - `"response.function_call_arguments.done"` - - `id: string` + - `agent: optional object { agent_name }` - The unique ID of the program output item. + The agent that owns this multi-agent streaming event. - - `call_id: string` + - `agent_name: string` - The call ID of the program item. + The canonical name of the agent that produced this item. - - `result: string` + - `BetaResponseInProgressEvent object { response, sequence_number, type, agent }` - The result produced by the program item. + Emitted when the response is in progress. - - `status: "completed" or "incomplete"` + - `response: BetaResponse` - The terminal status of the program output item. + The response that is in progress. - - `"completed"` + - `sequence_number: number` - - `"incomplete"` + The sequence number of this event. - - `type: "program_output"` + - `type: "response.in_progress"` - The type of the item. Always `program_output`. + The type of the event. Always `response.in_progress`. - - `"program_output"` + - `"response.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. - - `ToolSearchCall object { id, arguments, call_id, 5 more }` - - - `id: string` - - The unique ID of the tool search call item. + - `BetaResponseFailedEvent object { response, sequence_number, type, agent }` - - `arguments: unknown` + An event that is emitted when a response fails. - Arguments used for the tool search call. + - `response: BetaResponse` - - `call_id: string` + The response that failed. - The unique ID of the tool search call generated by the model. + - `sequence_number: number` - - `execution: "server" or "client"` + The sequence number of this event. - Whether tool search was executed by the server or by the client. + - `type: "response.failed"` - - `"server"` + The type of the event. Always `response.failed`. - - `"client"` + - `"response.failed"` - - `status: "in_progress" or "completed" or "incomplete"` + - `agent: optional object { agent_name }` - The status of the tool search call item that was recorded. + 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"` + - `BetaResponseIncompleteEvent object { response, sequence_number, type, agent }` - - `type: "tool_search_call"` + An event that is emitted when a response finishes as incomplete. - The type of the item. Always `tool_search_call`. + - `response: BetaResponse` - - `"tool_search_call"` + The response that was incomplete. - - `agent: optional object { agent_name }` + - `sequence_number: number` - The agent that produced this item. + The sequence number of this event. - - `agent_name: string` + - `type: "response.incomplete"` - The canonical name of the agent that produced this item. + The type of the event. Always `response.incomplete`. - - `created_by: optional string` + - `"response.incomplete"` - The identifier of the actor that created the item. + - `agent: optional object { agent_name }` - - `ToolSearchOutput object { id, call_id, execution, 5 more }` + The agent that owns this multi-agent streaming event. - - `id: string` + - `agent_name: string` - The unique ID of the tool search output item. + The canonical name of the agent that produced this item. - - `call_id: string` + - `BetaResponseOutputItemAddedEvent object { item, output_index, sequence_number, 2 more }` - The unique ID of the tool search call generated by the model. + Emitted when a new output item is added. - - `execution: "server" or "client"` + - `item: BetaResponseOutputItem` - Whether tool search was executed by the server or by the client. + The output item that was added. - - `"server"` + - `BetaResponseOutputMessage object { id, content, role, 4 more }` - - `"client"` + An output message from the model. - - `status: "in_progress" or "completed" or "incomplete"` + - `FileSearchCall object { id, queries, status, 3 more }` - The status of the tool search output item that was recorded. + The results of a file search tool call. See the + [file search guide](/docs/guides/tools-file-search) for more information. - - `"in_progress"` + - `FunctionCall object { arguments, call_id, name, 6 more }` - - `"completed"` + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. - - `"incomplete"` + - `FunctionCallOutput object { id, call_id, output, 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` + - `AgentMessage object { id, author, content, 3 more }` - The loaded tool definitions returned by tool search. + - `MultiAgentCall object { id, action, arguments, 3 more }` - - `Function object { name, parameters, strict, 5 more }` + - `MultiAgentCallOutput object { id, action, call_id, 3 more }` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `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 function to call. + - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` - - `parameters: map[unknown]` + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - A JSON schema object describing the parameters of the function. + - `ComputerCallOutput object { id, call_id, output, 5 more }` - - `strict: boolean` + - `Reasoning object { id, summary, type, 4 more }` - Whether strict parameter validation is enforced for this function tool. + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](/docs/guides/conversation-state). - - `type: "function"` + - `Program object { id, call_id, code, 3 more }` - The type of the function tool. Always `function`. + - `ProgramOutput object { id, call_id, result, 3 more }` - - `"function"` + - `ToolSearchCall object { id, arguments, call_id, 5 more }` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `ToolSearchOutput object { id, call_id, execution, 5 more }` - The tool invocation context(s). + - `AdditionalTools object { id, role, tools, 2 more }` - - `"direct"` + - `Compaction object { id, encrypted_content, type, 2 more }` - - `"programmatic"` + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). - - `defer_loading: optional boolean` + - `ImageGenerationCall object { id, result, status, 2 more }` - Whether this function is deferred and loaded via tool search. + An image generation request made by the model. - - `description: optional string` + - `CodeInterpreterCall object { id, code, container_id, 4 more }` - A description of the function. Used by the model to determine whether or not to call the function. + A tool call to run code. - - `output_schema: optional map[unknown]` + - `LocalShellCall object { id, action, call_id, 3 more }` - A JSON schema object describing the JSON value encoded in string outputs for this function. + A tool call to run a command on the local shell. - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + - `LocalShellCallOutput object { id, output, type, 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). + The output of a local shell tool call. - - `type: "file_search"` + - `ShellCall object { id, action, call_id, 6 more }` - The type of the file search tool. Always `file_search`. + A tool call that executes one or more shell commands in a managed environment. - - `"file_search"` + - `ShellCallOutput object { id, call_id, max_output_length, 6 more }` - - `vector_store_ids: array of string` + The output of a shell tool call that was emitted. - The IDs of the vector stores to search. + - `ApplyPatchCall object { id, call_id, operation, 5 more }` - - `filters: optional object { key, type, value } or object { filters, type }` + A tool call that applies file diffs by creating, deleting, or updating files. - A filter to apply. + - `ApplyPatchCallOutput object { id, call_id, status, 5 more }` - - `ComparisonFilter object { key, type, value }` + The output emitted by an apply patch tool call. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `McpCall object { id, arguments, name, 7 more }` - - `key: string` + An invocation of a tool on an MCP server. - The key to compare against the value. + - `McpListTools object { id, server_label, tools, 3 more }` - - `type: "eq" or "ne" or "gt" or 5 more` + A list of tools available on an MCP server. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `McpApprovalRequest object { id, arguments, name, 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 + A request for human approval of a tool invocation. - - `"eq"` + - `McpApprovalResponse object { id, approval_request_id, approve, 3 more }` - - `"ne"` + A response to an MCP approval request. - - `"gt"` + - `CustomToolCall object { call_id, input, name, 5 more }` - - `"gte"` + A call to a custom tool created by the model. - - `"lt"` + - `CustomToolCallOutput object { id, call_id, output, 5 more }` - - `"lte"` + - `output_index: number` - - `"in"` + The index of the output item that was added. - - `"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. + - `type: "response.output_item.added"` - - `string` + The type of the event. Always `response.output_item.added`. - - `number` + - `"response.output_item.added"` - - `boolean` + - `agent: optional object { agent_name }` - - `array of string or number` + The agent that owns this multi-agent streaming event. - - `string` + - `agent_name: string` - - `number` + The canonical name of the agent that produced this item. - - `CompoundFilter object { filters, type }` + - `BetaResponseOutputItemDoneEvent object { item, output_index, sequence_number, 2 more }` - Combine multiple filters using `and` or `or`. + Emitted when an output item is marked done. - - `filters: array of object { key, type, value } or unknown` + - `item: BetaResponseOutputItem` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + The output item that was marked done. - - `ComparisonFilter object { key, type, value }` + - `output_index: number` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The index of the output item that was marked done. - - `key: string` + - `sequence_number: number` - The key to compare against the value. + The sequence number of this event. - - `type: "eq" or "ne" or "gt" or 5 more` + - `type: "response.output_item.done"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The type of the event. Always `response.output_item.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 + - `"response.output_item.done"` - - `"eq"` + - `agent: optional object { agent_name }` - - `"ne"` + The agent that owns this multi-agent streaming event. - - `"gt"` + - `agent_name: string` - - `"gte"` + The canonical name of the agent that produced this item. - - `"lt"` + - `BetaResponseReasoningSummaryPartAddedEvent object { item_id, output_index, part, 4 more }` - - `"lte"` + Emitted when a new reasoning summary part is added. - - `"in"` + - `item_id: string` - - `"nin"` + The ID of the item this summary part is associated with. - - `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 this summary part is associated with. - - `string` + - `part: object { text, type }` - - `number` + The summary part that was added. - - `boolean` + - `text: string` - - `array of string or number` + The text of the summary part. - - `string` + - `type: "summary_text"` - - `number` + The type of the summary part. Always `summary_text`. - - `unknown` + - `"summary_text"` - - `type: "and" or "or"` + - `sequence_number: number` - Type of operation: `and` or `or`. + The sequence number of this event. - - `"and"` + - `summary_index: number` - - `"or"` + The index of the summary part within the reasoning summary. - - `max_num_results: optional number` + - `type: "response.reasoning_summary_part.added"` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + The type of the event. Always `response.reasoning_summary_part.added`. - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `"response.reasoning_summary_part.added"` - Ranking options for search. + - `agent: optional object { agent_name }` - - `hybrid_search: optional object { embedding_weight, text_weight }` + The agent that owns this multi-agent streaming event. - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `agent_name: string` - - `embedding_weight: number` + The canonical name of the agent that produced this item. - The weight of the embedding in the reciprocal ranking fusion. + - `BetaResponseReasoningSummaryPartDoneEvent object { item_id, output_index, part, 5 more }` - - `text_weight: number` + Emitted when a reasoning summary part is completed. - The weight of the text in the reciprocal ranking fusion. + - `item_id: string` - - `ranker: optional "auto" or "default-2024-11-15"` + The ID of the item this summary part is associated with. - The ranker to use for the file search. + - `output_index: number` - - `"auto"` + The index of the output item this summary part is associated with. - - `"default-2024-11-15"` + - `part: object { text, type }` - - `score_threshold: optional number` + The completed summary part. - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + - `text: string` - - `Computer object { type }` + The text of the summary part. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `type: "summary_text"` - - `type: "computer"` + The type of the summary part. Always `summary_text`. - The type of the computer tool. Always `computer`. + - `"summary_text"` - - `"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). + - `summary_index: number` - - `display_height: number` + The index of the summary part within the reasoning summary. - The height of the computer display. + - `type: "response.reasoning_summary_part.done"` - - `display_width: number` + The type of the event. Always `response.reasoning_summary_part.done`. - The width of the computer display. + - `"response.reasoning_summary_part.done"` - - `environment: "windows" or "mac" or "linux" or 2 more` + - `agent: optional object { agent_name }` - The type of computer environment to control. + The agent that owns this multi-agent streaming event. - - `"windows"` + - `agent_name: string` - - `"mac"` + The canonical name of the agent that produced this item. - - `"linux"` + - `status: optional "incomplete"` - - `"ubuntu"` + The completion status of the summary part. Omitted when the part completed + normally and set to `incomplete` when generation was interrupted. - - `"browser"` + - `"incomplete"` - - `type: "computer_use_preview"` + - `BetaResponseReasoningSummaryTextDeltaEvent object { delta, item_id, output_index, 4 more }` - The type of the computer use tool. Always `computer_use_preview`. + Emitted when a delta is added to a reasoning summary text. - - `"computer_use_preview"` + - `delta: string` - - `WebSearch object { type, filters, search_context_size, user_location }` + The text delta that was added to the summary. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `item_id: string` - - `type: "web_search" or "web_search_2025_08_26"` + The ID of the item this summary text delta is associated with. - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `output_index: number` - - `"web_search"` + The index of the output item this summary text delta is associated with. - - `"web_search_2025_08_26"` + - `sequence_number: number` - - `filters: optional object { allowed_domains }` + The sequence number of this event. - Filters for the search. + - `summary_index: number` - - `allowed_domains: optional array of string` + The index of the summary part within the reasoning summary. - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `type: "response.reasoning_summary_text.delta"` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + The type of the event. Always `response.reasoning_summary_text.delta`. - - `search_context_size: optional "low" or "medium" or "high"` + - `"response.reasoning_summary_text.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. + - `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 { city, country, region, 2 more }` + - `BetaResponseReasoningSummaryTextDoneEvent object { item_id, output_index, sequence_number, 4 more }` - The approximate location of the user. + Emitted when a reasoning summary text is completed. - - `city: optional string` + - `item_id: string` - Free text input for the city of the user, e.g. `San Francisco`. + The ID of the item this summary text is associated with. - - `country: optional string` + - `output_index: number` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The index of the output item this summary text is associated with. - - `region: optional string` + - `sequence_number: number` - Free text input for the region of the user, e.g. `California`. + The sequence number of this event. - - `timezone: optional string` + - `summary_index: number` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The index of the summary part within the reasoning summary. - - `type: optional "approximate"` + - `text: string` - The type of location approximation. Always `approximate`. + The full text of the completed reasoning summary. - - `"approximate"` + - `type: "response.reasoning_summary_text.done"` - - `Mcp object { server_label, type, allowed_callers, 9 more }` + The type of the event. Always `response.reasoning_summary_text.done`. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `"response.reasoning_summary_text.done"` - - `server_label: string` + - `agent: optional object { agent_name }` - A label for this MCP server, used to identify it in tool calls. + The agent that owns this multi-agent streaming event. - - `type: "mcp"` + - `agent_name: string` - The type of the MCP tool. Always `mcp`. + The canonical name of the agent that produced this item. - - `"mcp"` + - `BetaResponseReasoningTextDeltaEvent object { content_index, delta, item_id, 4 more }` - - `allowed_callers: optional array of "direct" or "programmatic"` + Emitted when a delta is added to a reasoning text. - The tool invocation context(s). + - `content_index: number` - - `"direct"` + The index of the reasoning content part this delta is associated with. - - `"programmatic"` + - `delta: string` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + The text delta that was added to the reasoning content. - List of allowed tool names or a filter object. + - `item_id: string` - - `McpAllowedTools = array of string` + The ID of the item this reasoning text delta is associated with. - A string array of allowed tool names + - `output_index: number` - - `McpToolFilter object { read_only, tool_names }` + The index of the output item this reasoning text delta is associated with. - A filter object to specify which tools are allowed. + - `sequence_number: number` - - `read_only: optional boolean` + The sequence number of this 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. + - `type: "response.reasoning_text.delta"` - - `tool_names: optional array of string` + The type of the event. Always `response.reasoning_text.delta`. - List of allowed tool names. + - `"response.reasoning_text.delta"` - - `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 owns this multi-agent streaming event. - - `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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + The canonical name of the agent that produced this item. - Currently supported `connector_id` values are: + - `BetaResponseReasoningTextDoneEvent object { content_index, item_id, output_index, 4 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` + Emitted when a reasoning text is completed. - - `"connector_dropbox"` + - `content_index: number` - - `"connector_gmail"` + The index of the reasoning content part. - - `"connector_googlecalendar"` + - `item_id: string` - - `"connector_googledrive"` + The ID of the item this reasoning text is associated with. - - `"connector_microsoftteams"` + - `output_index: number` - - `"connector_outlookcalendar"` + The index of the output item this reasoning text is associated with. - - `"connector_outlookemail"` + - `sequence_number: number` - - `"connector_sharepoint"` + The sequence number of this event. - - `defer_loading: optional boolean` + - `text: string` - Whether this MCP tool is deferred and discovered via tool search. + The full text of the completed reasoning content. - - `headers: optional map[string]` + - `type: "response.reasoning_text.done"` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + The type of the event. Always `response.reasoning_text.done`. - - `require_approval: optional object { always, never } or "always" or "never"` + - `"response.reasoning_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. + - `BetaResponseRefusalDeltaEvent object { content_index, delta, item_id, 4 more }` - - `read_only: optional boolean` + Emitted when there is a partial refusal text. - 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. + - `content_index: number` - - `tool_names: optional array of string` + The index of the content part that the refusal text is added to. - List of allowed tool names. + - `delta: string` - - `never: optional object { read_only, tool_names }` + The refusal text that is added. - A filter object to specify which tools are allowed. + - `item_id: string` - - `read_only: optional boolean` + The ID of the output item that the refusal text is added to. - 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 that the refusal text is added to. - List of allowed tool names. + - `sequence_number: number` - - `McpToolApprovalSetting = "always" or "never"` + The sequence number of this 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. + - `type: "response.refusal.delta"` - - `"always"` + The type of the event. Always `response.refusal.delta`. - - `"never"` + - `"response.refusal.delta"` - - `server_description: optional string` + - `agent: optional object { agent_name }` - Optional description of the MCP server, used to provide more context. + The agent that owns this multi-agent streaming event. - - `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` + - `BetaResponseRefusalDoneEvent object { content_index, item_id, output_index, 4 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 refusal text is finalized. - - `CodeInterpreter object { container, type, allowed_callers }` + - `content_index: number` - A tool that runs Python code to help generate a response to a prompt. + The index of the content part that the refusal text is finalized. - - `container: string or object { type, file_ids, memory_limit, network_policy }` + - `item_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 output item that the refusal text is finalized. - - `string` + - `output_index: number` - The container ID. + The index of the output item that the refusal text is finalized. - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + - `refusal: string` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + The refusal text that is finalized. - - `type: "auto"` + - `sequence_number: number` - Always `auto`. + The sequence number of this event. - - `"auto"` + - `type: "response.refusal.done"` - - `file_ids: optional array of string` + The type of the event. Always `response.refusal.done`. - An optional list of uploaded files to make available to your code. + - `"response.refusal.done"` - - `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"` + - `BetaResponseTextDeltaEvent object { content_index, delta, item_id, 5 more }` - - `"64g"` + Emitted when there is an additional text delta. - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `content_index: number` - Network access policy for the container. + The index of the content part that the text delta was added to. - - `BetaContainerNetworkPolicyDisabled object { type }` + - `delta: string` - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + The text delta that was added. - - `type: "code_interpreter"` + - `item_id: string` - The type of the code interpreter tool. Always `code_interpreter`. + The ID of the output item that the text delta was added to. - - `"code_interpreter"` + - `logprobs: array of object { token, logprob, top_logprobs }` - - `allowed_callers: optional array of "direct" or "programmatic"` + The log probabilities of the tokens in the delta. - The tool invocation context(s). + - `token: string` - - `"direct"` + A possible text token. - - `"programmatic"` + - `logprob: number` - - `ProgrammaticToolCalling object { type }` + The log probability of this token. - - `type: "programmatic_tool_calling"` + - `top_logprobs: optional array of object { token, logprob }` - The type of the tool. Always `programmatic_tool_calling`. + The log probabilities of up to 20 of the most likely tokens. - - `"programmatic_tool_calling"` + - `token: optional string` - - `ImageGeneration object { type, action, background, 9 more }` + A possible text token. - A tool that generates images using the GPT image models. + - `logprob: optional number` - - `type: "image_generation"` + The log probability of this token. - The type of the image generation tool. Always `image_generation`. + - `output_index: number` - - `"image_generation"` + The index of the output item that the text delta was added to. - - `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 for this event. - - `"generate"` + - `type: "response.output_text.delta"` - - `"edit"` + The type of the event. Always `response.output_text.delta`. - - `"auto"` + - `"response.output_text.delta"` - - `background: optional "transparent" or "opaque" or "auto"` + - `agent: optional object { agent_name }` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + The agent that owns this multi-agent streaming event. - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + - `agent_name: string` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + The canonical name of the agent that produced this item. - - `"transparent"` + - `BetaResponseTextDoneEvent object { content_index, item_id, logprobs, 5 more }` - - `"opaque"` + Emitted when text content is finalized. - - `"auto"` + - `content_index: number` - - `input_fidelity: optional "high" or "low"` + The index of the content part that the text content is finalized. - 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`. + - `item_id: string` - - `"high"` + The ID of the output item that the text content is finalized. - - `"low"` + - `logprobs: array of object { token, logprob, top_logprobs }` - - `input_image_mask: optional object { file_id, image_url }` + The log probabilities of the tokens in the delta. - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `token: string` - - `file_id: optional string` + A possible text token. - File ID for the mask image. + - `logprob: number` - - `image_url: optional string` + The log probability of this token. - Base64-encoded mask image. + - `top_logprobs: optional array of object { token, logprob }` - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + The log probabilities of up to 20 of the most likely tokens. - The image generation model to use. Default: `gpt-image-1`. + - `token: optional string` - - `string` + A possible text token. - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `logprob: optional number` - The image generation model to use. Default: `gpt-image-1`. + The log probability of this token. - - `"gpt-image-1"` + - `output_index: number` - - `"gpt-image-1-mini"` + The index of the output item that the text content is finalized. - - `"gpt-image-2"` + - `sequence_number: number` - - `"gpt-image-2-2026-04-21"` + The sequence number for this event. - - `"gpt-image-1.5"` + - `text: string` - - `"chatgpt-image-latest"` + The text content that is finalized. - - `moderation: optional "auto" or "low"` + - `type: "response.output_text.done"` - Moderation level for the generated image. Default: `auto`. + The type of the event. Always `response.output_text.done`. - - `"auto"` + - `"response.output_text.done"` - - `"low"` + - `agent: optional object { agent_name }` - - `output_compression: optional number` + The agent that owns this multi-agent streaming event. - Compression level for the output image. Default: 100. + - `agent_name: string` - - `output_format: optional "png" or "webp" or "jpeg"` + The canonical name of the agent that produced this item. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `BetaResponseWebSearchCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` - - `"png"` + Emitted when a web search call is completed. - - `"webp"` + - `item_id: string` - - `"jpeg"` + Unique ID for the output item associated with the web search call. - - `partial_images: optional number` + - `output_index: number` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + The index of the output item that the web search call is associated with. - - `quality: optional "low" or "medium" or "high" or "auto"` + - `sequence_number: number` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + The sequence number of the web search call being processed. - - `"low"` + - `type: "response.web_search_call.completed"` - - `"medium"` + The type of the event. Always `response.web_search_call.completed`. - - `"high"` + - `"response.web_search_call.completed"` - - `"auto"` + - `agent: optional object { agent_name }` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + The agent that owns this multi-agent streaming 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`. + - `agent_name: string` - - `string` + The canonical name of the agent that produced this item. - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `BetaResponseWebSearchCallInProgressEvent object { item_id, output_index, sequence_number, 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`. + Emitted when a web search call is initiated. - - `"1024x1024"` + - `item_id: string` - - `"1024x1536"` + Unique ID for the output item associated with the web search call. - - `"1536x1024"` + - `output_index: number` - - `"auto"` + The index of the output item that the web search call is associated with. - - `LocalShell object { type }` + - `sequence_number: number` - A tool that allows the model to execute shell commands in a local environment. + The sequence number of the web search call being processed. - - `type: "local_shell"` + - `type: "response.web_search_call.in_progress"` - The type of the local shell tool. Always `local_shell`. + The type of the event. Always `response.web_search_call.in_progress`. - - `"local_shell"` + - `"response.web_search_call.in_progress"` - - `Shell object { type, allowed_callers, environment }` + - `agent: optional object { agent_name }` - A tool that allows the model to execute shell commands. + The agent that owns this multi-agent streaming event. - - `type: "shell"` + - `agent_name: string` - The type of the shell tool. Always `shell`. + The canonical name of the agent that produced this item. - - `"shell"` + - `BetaResponseWebSearchCallSearchingEvent object { item_id, output_index, sequence_number, 2 more }` - - `allowed_callers: optional array of "direct" or "programmatic"` + Emitted when a web search call is executing. - The tool invocation context(s). + - `item_id: string` - - `"direct"` + Unique ID for the output item associated with the web search call. - - `"programmatic"` + - `output_index: number` - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + The index of the output item that the web search call is associated with. - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `sequence_number: number` - - `BetaLocalEnvironment object { type, skills }` + The sequence number of the web search call being processed. - - `BetaContainerReference object { container_id, type }` + - `type: "response.web_search_call.searching"` - - `Custom object { name, type, allowed_callers, 3 more }` + The type of the event. Always `response.web_search_call.searching`. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `"response.web_search_call.searching"` - - `name: string` + - `agent: optional object { agent_name }` - The name of the custom tool, used to identify it in tool calls. + The agent that owns this multi-agent streaming event. - - `type: "custom"` + - `agent_name: string` - The type of the custom tool. Always `custom`. + The canonical name of the agent that produced this item. - - `"custom"` + - `BetaResponseImageGenCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` - - `allowed_callers: optional array of "direct" or "programmatic"` + Emitted when an image generation tool call has completed and the final image is available. - The tool invocation context(s). + - `item_id: string` - - `"direct"` + The unique identifier of the image generation item being processed. - - `"programmatic"` + - `output_index: number` - - `defer_loading: optional boolean` + The index of the output item in the response's output array. - Whether this tool should be deferred and discovered via tool search. + - `sequence_number: number` - - `description: optional string` + The sequence number of this event. - Optional description of the custom tool, used to provide more context. + - `type: "response.image_generation_call.completed"` - - `format: optional object { type } or object { definition, syntax, type }` + The type of the event. Always 'response.image_generation_call.completed'. - The input format for the custom tool. Default is unconstrained text. + - `"response.image_generation_call.completed"` - - `Text object { type }` + - `agent: optional object { agent_name }` - Unconstrained free-form text. + The agent that owns this multi-agent streaming event. - - `type: "text"` + - `agent_name: string` - Unconstrained text format. Always `text`. + The canonical name of the agent that produced this item. - - `"text"` + - `BetaResponseImageGenCallGeneratingEvent object { item_id, output_index, sequence_number, 2 more }` - - `Grammar object { definition, syntax, type }` + Emitted when an image generation tool call is actively generating an image (intermediate state). - A grammar defined by the user. + - `item_id: string` - - `definition: string` + The unique identifier of the image generation item being processed. - The grammar definition. + - `output_index: number` - - `syntax: "lark" or "regex"` + The index of the output item in the response's output array. - The syntax of the grammar definition. One of `lark` or `regex`. + - `sequence_number: number` - - `"lark"` + The sequence number of the image generation item being processed. - - `"regex"` + - `type: "response.image_generation_call.generating"` - - `type: "grammar"` + The type of the event. Always 'response.image_generation_call.generating'. - Grammar format. Always `grammar`. + - `"response.image_generation_call.generating"` - - `"grammar"` + - `agent: optional object { agent_name }` - - `Namespace object { description, name, tools, type }` + The agent that owns this multi-agent streaming event. - 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. + - `BetaResponseImageGenCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` - - `name: string` + Emitted when an image generation tool call is in progress. - The namespace name used in tool calls (for example, `crm`). + - `item_id: string` - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + The unique identifier of the image generation item being processed. - The function/custom tools available inside this namespace. + - `output_index: number` - - `Function object { name, type, allowed_callers, 5 more }` + The index of the output item in the response's output array. - - `name: string` + - `sequence_number: number` - - `type: "function"` + The sequence number of the image generation item being processed. - - `"function"` + - `type: "response.image_generation_call.in_progress"` - - `allowed_callers: optional array of "direct" or "programmatic"` + The type of the event. Always 'response.image_generation_call.in_progress'. - The tool invocation context(s). + - `"response.image_generation_call.in_progress"` - - `"direct"` + - `agent: optional object { agent_name }` - - `"programmatic"` + The agent that owns this multi-agent streaming event. - - `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` + - `BetaResponseImageGenCallPartialImageEvent object { item_id, output_index, partial_image_b64, 4 more }` - - `output_schema: optional map[unknown]` + Emitted when a partial image is available during image generation streaming. - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `item_id: string` - - `parameters: optional unknown` + The unique identifier of the image generation item being processed. - - `strict: optional boolean` + - `output_index: 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 index of the output item in the response's output array. - - `Custom object { name, type, allowed_callers, 3 more }` + - `partial_image_b64: string` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + Base64-encoded partial image data, suitable for rendering as an image. - - `name: string` + - `partial_image_index: number` - The name of the custom tool, used to identify it in tool calls. + 0-based index for the partial image (backend is 1-based, but this is 0-based for the user). - - `type: "custom"` + - `sequence_number: number` - The type of the custom tool. Always `custom`. + The sequence number of the image generation item being processed. - - `"custom"` + - `type: "response.image_generation_call.partial_image"` - - `allowed_callers: optional array of "direct" or "programmatic"` + The type of the event. Always 'response.image_generation_call.partial_image'. - The tool invocation context(s). + - `"response.image_generation_call.partial_image"` - - `"direct"` + - `agent: optional object { agent_name }` - - `"programmatic"` + The agent that owns this multi-agent streaming event. - - `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` + - `BetaResponseMcpCallArgumentsDeltaEvent object { delta, item_id, output_index, 3 more }` - Optional description of the custom tool, used to provide more context. + Emitted when there is a delta (partial update) to the arguments of an MCP tool call. - - `format: optional object { type } or object { definition, syntax, type }` + - `delta: string` - The input format for the custom tool. Default is unconstrained text. + A JSON string containing the partial update to the arguments for the MCP tool call. - - `Text object { type }` + - `item_id: string` - Unconstrained free-form text. + The unique identifier of the MCP tool call item being processed. - - `type: "text"` + - `output_index: number` - Unconstrained text format. Always `text`. + The index of the output item in the response's output array. - - `"text"` + - `sequence_number: number` - - `Grammar object { definition, syntax, type }` + The sequence number of this event. - A grammar defined by the user. + - `type: "response.mcp_call_arguments.delta"` - - `definition: string` + The type of the event. Always 'response.mcp_call_arguments.delta'. - The grammar definition. + - `"response.mcp_call_arguments.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"` + - `BetaResponseMcpCallArgumentsDoneEvent object { arguments, item_id, output_index, 3 more }` - Grammar format. Always `grammar`. + Emitted when the arguments for an MCP tool call are finalized. - - `"grammar"` + - `arguments: string` - - `type: "namespace"` + A JSON string containing the finalized arguments for the MCP tool call. - The type of the tool. Always `namespace`. + - `item_id: string` - - `"namespace"` + The unique identifier of the MCP tool call item being processed. - - `ToolSearch object { type, description, execution, parameters }` + - `output_index: number` - Hosted or BYOT tool search configuration for deferred tools. + The index of the output item in the response's output array. - - `type: "tool_search"` + - `sequence_number: number` - The type of the tool. Always `tool_search`. + The sequence number of this event. - - `"tool_search"` + - `type: "response.mcp_call_arguments.done"` - - `description: optional string` + The type of the event. Always 'response.mcp_call_arguments.done'. - Description shown to the model for a client-executed tool search tool. + - `"response.mcp_call_arguments.done"` - - `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 owns this multi-agent streaming event. - - `"server"` + - `agent_name: string` - - `"client"` + The canonical name of the agent that produced this item. - - `parameters: optional unknown` + - `BetaResponseMcpCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` - Parameter schema for a client-executed tool search tool. + Emitted when an MCP tool call has completed successfully. - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + - `item_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 MCP tool call item that completed. - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `output_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 output item that completed. - - `"web_search_preview"` + - `sequence_number: number` - - `"web_search_preview_2025_03_11"` + The sequence number of this event. - - `search_content_types: optional array of "text" or "image"` + - `type: "response.mcp_call.completed"` - - `"text"` + The type of the event. Always 'response.mcp_call.completed'. - - `"image"` + - `"response.mcp_call.completed"` - - `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 owns this multi-agent streaming event. - - `"low"` + - `agent_name: string` - - `"medium"` + The canonical name of the agent that produced this item. - - `"high"` + - `BetaResponseMcpCallFailedEvent object { item_id, output_index, sequence_number, 2 more }` - - `user_location: optional object { type, city, country, 2 more }` + Emitted when an MCP tool call has failed. - The user's location. + - `item_id: string` - - `type: "approximate"` + The ID of the MCP tool call item that failed. - The type of location approximation. Always `approximate`. + - `output_index: number` - - `"approximate"` + The index of the output item that failed. - - `city: optional string` + - `sequence_number: number` - Free text input for the city of the user, e.g. `San Francisco`. + The sequence number of this event. - - `country: optional string` + - `type: "response.mcp_call.failed"` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The type of the event. Always 'response.mcp_call.failed'. - - `region: optional string` + - `"response.mcp_call.failed"` - Free text input for the region of the user, e.g. `California`. + - `agent: optional object { agent_name }` - - `timezone: optional string` + The agent that owns this multi-agent streaming event. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `agent_name: string` - - `ApplyPatch object { type, allowed_callers }` + The canonical name of the agent that produced this item. - Allows the assistant to create, delete, or update files using unified diffs. + - `BetaResponseMcpCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` - - `type: "apply_patch"` + Emitted when an MCP tool call is in progress. - The type of the tool. Always `apply_patch`. + - `item_id: string` - - `"apply_patch"` + The unique identifier of the MCP tool call item being processed. - - `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. - - `type: "tool_search_output"` + - `type: "response.mcp_call.in_progress"` - The type of the item. Always `tool_search_output`. + The type of the event. Always 'response.mcp_call.in_progress'. - - `"tool_search_output"` + - `"response.mcp_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. - - `created_by: optional string` + - `BetaResponseMcpListToolsCompletedEvent object { item_id, output_index, sequence_number, 2 more }` - The identifier of the actor that created the item. + Emitted when the list of available MCP tools has been successfully retrieved. - - `AdditionalTools object { id, role, tools, 2 more }` + - `item_id: string` - - `id: string` + The ID of the MCP tool call item that produced this output. - The unique ID of the additional tools item. + - `output_index: number` - - `role: "unknown" or "user" or "assistant" or 5 more` + The index of the output item that was processed. - The role that provided the additional tools. + - `sequence_number: number` - - `"unknown"` + The sequence number of this event. - - `"user"` + - `type: "response.mcp_list_tools.completed"` - - `"assistant"` + The type of the event. Always 'response.mcp_list_tools.completed'. - - `"system"` + - `"response.mcp_list_tools.completed"` - - `"critic"` + - `agent: optional object { agent_name }` - - `"discriminator"` + The agent that owns this multi-agent streaming event. - - `"developer"` + - `agent_name: string` - - `"tool"` + The canonical name of the agent that produced this 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` + - `BetaResponseMcpListToolsFailedEvent object { item_id, output_index, sequence_number, 2 more }` - The additional tool definitions made available at this item. + Emitted when the attempt to list available MCP tools has failed. - - `Function object { name, parameters, strict, 5 more }` + - `item_id: string` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + The ID of the MCP tool call item that failed. - - `name: string` + - `output_index: number` - The name of the function to call. + The index of the output item that failed. - - `parameters: map[unknown]` + - `sequence_number: number` - A JSON schema object describing the parameters of the function. + The sequence number of this event. - - `strict: boolean` + - `type: "response.mcp_list_tools.failed"` - Whether strict parameter validation is enforced for this function tool. + The type of the event. Always 'response.mcp_list_tools.failed'. - - `type: "function"` + - `"response.mcp_list_tools.failed"` - The type of the function tool. Always `function`. + - `agent: optional object { agent_name }` - - `"function"` + 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"` + - `BetaResponseMcpListToolsInProgressEvent object { item_id, output_index, sequence_number, 2 more }` - - `"programmatic"` + Emitted when the system is in the process of retrieving the list of available MCP tools. - - `defer_loading: optional boolean` + - `item_id: string` - Whether this function is deferred and loaded via tool search. + The ID of the MCP tool call item that is being processed. - - `description: optional string` + - `output_index: number` + + The index of the output item that is being processed. + + - `sequence_number: number` + + The sequence number of this event. + + - `type: "response.mcp_list_tools.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.mcp_list_tools.in_progress'. - - `output_schema: optional map[unknown]` + - `"response.mcp_list_tools.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`. + - `BetaResponseOutputTextAnnotationAddedEvent object { annotation, annotation_index, content_index, 5 more }` - - `"file_search"` + Emitted when an annotation is added to output text content. - - `vector_store_ids: array of string` + - `annotation: unknown` - The IDs of the vector stores to search. + The annotation object being added. (See annotation schema for details.) - - `filters: optional object { key, type, value } or object { filters, type }` + - `annotation_index: number` - A filter to apply. + The index of the annotation within the content part. - - `ComparisonFilter object { key, type, value }` + - `content_index: number` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The index of the content part within the output item. - - `key: string` + - `item_id: string` - The key to compare against the value. + The unique identifier of the item to which the annotation is being added. - - `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.output_text.annotation.added"` - - `"gt"` + The type of the event. Always 'response.output_text.annotation.added'. - - `"gte"` + - `"response.output_text.annotation.added"` - - `"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` + - `BetaResponseQueuedEvent object { response, sequence_number, type, agent }` - The value to compare against the attribute key; supports string, number, or boolean types. + Emitted when a response is queued and waiting to be processed. - - `string` + - `response: BetaResponse` - - `number` + The full response object that is queued. - - `boolean` + - `sequence_number: number` - - `array of string or number` + The sequence number for this event. - - `string` + - `type: "response.queued"` - - `number` + The type of the event. Always 'response.queued'. - - `CompoundFilter object { filters, type }` + - `"response.queued"` - Combine multiple filters using `and` or `or`. + - `agent: optional object { agent_name }` - - `filters: array of object { key, type, value } or unknown` + The agent that owns this multi-agent streaming event. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `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. + - `BetaResponseCustomToolCallInputDeltaEvent object { delta, item_id, output_index, 3 more }` - - `key: string` + Event representing a delta (partial update) to the input of a custom tool call. - The key to compare against the value. + - `delta: string` - - `type: "eq" or "ne" or "gt" or 5 more` + The incremental input data (delta) for the custom tool call. - 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 + Unique identifier for the API item associated with this event. - - `"eq"` + - `output_index: number` - - `"ne"` + The index of the output this delta applies to. - - `"gt"` + - `sequence_number: number` - - `"gte"` + The sequence number of this event. - - `"lt"` + - `type: "response.custom_tool_call_input.delta"` - - `"lte"` + The event type identifier. - - `"in"` + - `"response.custom_tool_call_input.delta"` - - `"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` + - `BetaResponseCustomToolCallInputDoneEvent object { input, item_id, output_index, 3 more }` - - `boolean` + Event indicating that input for a custom tool call is complete. - - `array of string or number` + - `input: string` - - `string` + The complete input data for the custom tool call. - - `number` + - `item_id: string` - - `unknown` + Unique identifier for the API item associated with this event. - - `type: "and" or "or"` + - `output_index: number` - Type of operation: `and` or `or`. + The index of the output this event applies to. - - `"and"` + - `sequence_number: number` - - `"or"` + The sequence number of this event. - - `max_num_results: optional number` + - `type: "response.custom_tool_call_input.done"` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + The event type identifier. - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `"response.custom_tool_call_input.done"` - Ranking options for search. + - `agent: optional object { agent_name }` - - `hybrid_search: optional object { embedding_weight, text_weight }` + The agent that owns this multi-agent streaming event. - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `agent_name: string` - - `embedding_weight: number` + The canonical name of the agent that produced this item. - The weight of the embedding in the reciprocal ranking fusion. +### Beta Response Text Config - - `text_weight: number` +- `BetaResponseTextConfig object { format, verbosity }` - The weight of the text in the reciprocal ranking fusion. + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - - `ranker: optional "auto" or "default-2024-11-15"` + - [Text inputs and outputs](/docs/guides/text) + - [Structured Outputs](/docs/guides/structured-outputs) - The ranker to use for the file search. + - `format: optional BetaResponseFormatTextConfig` - - `"auto"` + An object specifying the format that the model must output. - - `"default-2024-11-15"` + 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). - - `score_threshold: optional number` + The default format is `{ "type": "text" }` with no additional options. - 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. + **Not recommended for gpt-4o and newer models:** - - `Computer object { type }` + 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 tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `Text object { type }` - - `type: "computer"` + Default response format. Used to generate text responses. - The type of the computer tool. Always `computer`. + - `type: "text"` - - `"computer"` + The type of response format being defined. Always `text`. - - `ComputerUsePreview object { display_height, display_width, environment, type }` + - `"text"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` - - `display_height: number` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - The height of the computer display. + - `name: string` - - `display_width: 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 width of the computer display. + - `schema: map[unknown]` - - `environment: "windows" or "mac" or "linux" or 2 more` + 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 computer environment to control. + - `type: "json_schema"` - - `"windows"` + The type of response format being defined. Always `json_schema`. - - `"mac"` + - `"json_schema"` - - `"linux"` + - `description: optional string` - - `"ubuntu"` + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `"browser"` + - `strict: optional boolean` - - `type: "computer_use_preview"` + 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 computer use tool. Always `computer_use_preview`. + - `JSONObject object { type }` - - `"computer_use_preview"` + 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. - - `WebSearch object { type, filters, search_context_size, user_location }` + - `type: "json_object"` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The type of response format being defined. Always `json_object`. - - `type: "web_search" or "web_search_2025_08_26"` + - `"json_object"` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `verbosity: optional "low" or "medium" or "high"` - - `"web_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`. - - `"web_search_2025_08_26"` + - `"low"` - - `filters: optional object { allowed_domains }` + - `"medium"` - Filters for the search. + - `"high"` - - `allowed_domains: optional array of string` +### Beta Response Text Delta Event - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. +- `BetaResponseTextDeltaEvent object { content_index, delta, item_id, 5 more }` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + Emitted when there is an additional text delta. - - `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 delta was added to. - - `"low"` + - `delta: string` - - `"medium"` + The text delta that was added. - - `"high"` + - `item_id: string` - - `user_location: optional object { city, country, region, 2 more }` + The ID of the output item that the text delta was added to. - The approximate location of the user. + - `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` - - `type: optional "approximate"` + A possible text token. - The type of location approximation. Always `approximate`. + - `logprob: optional number` - - `"approximate"` + The log probability of this token. - - `Mcp object { server_label, type, allowed_callers, 9 more }` + - `output_index: number` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + The index of the output item that the text delta was added to. - - `server_label: string` + - `sequence_number: number` - A label for this MCP server, used to identify it in tool calls. + The sequence number for this event. - - `type: "mcp"` + - `type: "response.output_text.delta"` - The type of the MCP tool. Always `mcp`. + The type of the event. Always `response.output_text.delta`. - - `"mcp"` + - `"response.output_text.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. - - `allowed_tools: optional array of string or object { read_only, tool_names }` +### Beta Response Text Done Event - List of allowed tool names or a filter object. +- `BetaResponseTextDoneEvent object { content_index, item_id, logprobs, 5 more }` - - `McpAllowedTools = array of string` + Emitted when text content is finalized. - A string array of allowed tool names + - `content_index: number` - - `McpToolFilter object { read_only, tool_names }` + The index of the content part that the text content is finalized. - A filter object to specify which tools are allowed. + - `item_id: string` - - `read_only: optional boolean` + The ID of the output item that the text content is finalized. - 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. + - `logprobs: array of object { token, logprob, top_logprobs }` - - `tool_names: optional array of string` + The log probabilities of the tokens in the delta. - List of allowed tool names. + - `token: string` - - `authorization: optional string` + A possible text token. - 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. + - `logprob: number` - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + The log probability of this token. - 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + - `top_logprobs: optional array of object { token, logprob }` - Currently supported `connector_id` values are: + The log probabilities of up to 20 of the most likely 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` + - `token: optional string` - - `"connector_dropbox"` + A possible text token. - - `"connector_gmail"` + - `logprob: optional number` - - `"connector_googlecalendar"` + The log probability of this token. - - `"connector_googledrive"` + - `output_index: number` - - `"connector_microsoftteams"` + The index of the output item that the text content is finalized. - - `"connector_outlookcalendar"` + - `sequence_number: number` - - `"connector_outlookemail"` + The sequence number for this event. - - `"connector_sharepoint"` + - `text: string` - - `defer_loading: optional boolean` + The text content that is finalized. - Whether this MCP tool is deferred and discovered via tool search. + - `type: "response.output_text.done"` - - `headers: optional map[string]` + The type of the event. Always `response.output_text.done`. - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `"response.output_text.done"` - - `require_approval: optional object { always, never } or "always" or "never"` + - `agent: optional object { agent_name }` - Specify which of the MCP server's tools require approval. + The agent that owns this multi-agent streaming event. - - `McpToolApprovalFilter object { always, never }` + - `agent_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 canonical name of the agent that produced this item. - - `always: optional object { read_only, tool_names }` +### Beta Response Usage - A filter object to specify which tools are allowed. +- `BetaResponseUsage object { input_tokens, input_tokens_details, output_tokens, 2 more }` - - `read_only: optional boolean` + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `input_tokens: number` - - `tool_names: optional array of string` + The number of input tokens. - List of allowed tool names. + - `input_tokens_details: object { cache_write_tokens, cached_tokens }` - - `never: optional object { read_only, tool_names }` + A detailed breakdown of the input tokens. - A filter object to specify which tools are allowed. + - `cache_write_tokens: number` - - `read_only: optional boolean` + The number of input tokens that were written to the cache. - 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. + - `cached_tokens: number` - - `tool_names: optional array of string` + The number of tokens that were retrieved from the cache. + [More on prompt caching](/docs/guides/prompt-caching). - List of allowed tool names. + - `output_tokens: number` - - `McpToolApprovalSetting = "always" or "never"` + The number of output tokens. - 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_tokens_details: object { reasoning_tokens }` - - `"always"` + A detailed breakdown of the output tokens. - - `"never"` + - `reasoning_tokens: number` - - `server_description: optional string` + The number of reasoning tokens. - Optional description of the MCP server, used to provide more context. + - `total_tokens: number` - - `server_url: optional string` + The total number of tokens used. - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. +### Beta Response Web Search Call Completed Event - - `tunnel_id: optional string` +- `BetaResponseWebSearchCallCompletedEvent 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 completed. - - `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.completed"` - 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.completed`. - - `type: "auto"` + - `"response.web_search_call.completed"` - 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 Response Web Search Call In Progress Event - The memory limit for the code interpreter container. +- `BetaResponseWebSearchCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` - - `"1g"` + Emitted when a web search call is initiated. - - `"4g"` + - `item_id: string` - - `"16g"` + Unique ID for the output item associated with the web search call. - - `"64g"` + - `output_index: number` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + The index of the output item that the web search call is associated with. - Network access policy for the container. + - `sequence_number: number` - - `BetaContainerNetworkPolicyDisabled object { type }` + The sequence number of the web search call being processed. - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `type: "response.web_search_call.in_progress"` - - `type: "code_interpreter"` + The type of the event. Always `response.web_search_call.in_progress`. - The type of the code interpreter tool. Always `code_interpreter`. + - `"response.web_search_call.in_progress"` - - `"code_interpreter"` + - `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"` +### Beta Response Web Search Call Searching Event - - `ProgrammaticToolCalling object { type }` +- `BetaResponseWebSearchCallSearchingEvent object { item_id, output_index, sequence_number, 2 more }` - - `type: "programmatic_tool_calling"` + Emitted when a web search call is executing. - The type of the tool. Always `programmatic_tool_calling`. + - `item_id: string` - - `"programmatic_tool_calling"` + Unique ID for the output item associated with the web search call. - - `ImageGeneration object { type, action, background, 9 more }` + - `output_index: number` - A tool that generates images using the GPT image models. + The index of the output item that the web search call is associated with. - - `type: "image_generation"` + - `sequence_number: number` - The type of the image generation tool. Always `image_generation`. + The sequence number of the web search call being processed. - - `"image_generation"` + - `type: "response.web_search_call.searching"` - - `action: optional "generate" or "edit" or "auto"` + The type of the event. Always `response.web_search_call.searching`. - Whether to generate a new image or edit an existing image. Default: `auto`. + - `"response.web_search_call.searching"` - - `"generate"` + - `agent: optional object { agent_name }` - - `"edit"` + The agent that owns this multi-agent streaming event. - - `"auto"` + - `agent_name: string` - - `background: optional "transparent" or "opaque" or "auto"` + The canonical name of the agent that produced this item. - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. +### Beta Responses Client Event - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. +- `BetaResponsesClientEvent = object { type, background, context_management, 30 more } or BetaResponseInjectEvent` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + Client events accepted by the Responses WebSocket server. - - `"transparent"` + - `ResponseCreate object { type, background, context_management, 30 more }` - - `"opaque"` + Client event for creating a response over a persistent WebSocket connection. + This payload uses the same top-level fields as `POST /v1/responses`. - - `"auto"` + Notes: - - `input_fidelity: optional "high" or "low"` + - `stream` is implicit over WebSocket and should not be sent. + - `background` is not supported over WebSocket. - 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: "response.create"` - - `"high"` + The type of the client event. Always `response.create`. - - `"low"` + - `"response.create"` - - `input_image_mask: optional object { file_id, image_url }` + - `background: optional boolean` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + Whether to run the model response in the background. + [Learn more](/docs/guides/background). - - `file_id: optional string` + - `context_management: optional array of object { type, compact_threshold }` - File ID for the mask image. + Context management configuration for this request. - - `image_url: optional string` + - `type: string` - Base64-encoded mask image. + The context management entry type. Currently only 'compaction' is supported. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `compact_threshold: optional number` - The image generation model to use. Default: `gpt-image-1`. + Token threshold at which compaction should be triggered for this entry. - - `string` + - `conversation: optional string or BetaResponseConversationParam` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + 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. - The image generation model to use. Default: `gpt-image-1`. + - `ConversationID = string` - - `"gpt-image-1"` + The unique ID of the conversation. - - `"gpt-image-1-mini"` + - `BetaResponseConversationParam object { id }` - - `"gpt-image-2"` + The conversation that this response belongs to. - - `"gpt-image-2-2026-04-21"` + - `id: string` - - `"gpt-image-1.5"` + The unique ID of the conversation. - - `"chatgpt-image-latest"` + - `include: optional array of BetaResponseIncludable` - - `moderation: optional "auto" or "low"` + Specify additional output data to include in the model response. Currently supported values are: - Moderation level for the generated image. Default: `auto`. + - `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). - - `"auto"` + - `"file_search_call.results"` - - `"low"` + - `"web_search_call.results"` - - `output_compression: optional number` + - `"web_search_call.action.sources"` - Compression level for the output image. Default: 100. + - `"message.input_image.image_url"` - - `output_format: optional "png" or "webp" or "jpeg"` + - `"computer_call_output.output.image_url"` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `"code_interpreter_call.outputs"` - - `"png"` + - `"reasoning.encrypted_content"` - - `"webp"` + - `"message.output_text.logprobs"` - - `"jpeg"` + - `input: optional string or array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` - - `partial_images: optional number` + Text, image, or file inputs to the model, used to generate a response. - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + Learn more: - - `quality: optional "low" or "medium" or "high" or "auto"` + - [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 quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `TextInput = string` - - `"low"` + A text input to the model, equivalent to a text input with the + `user` 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](https://platform.openai.com/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](https://platform.openai.com/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](https://platform.openai.com/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 }` @@ -172678,39 +171854,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. + + - `"commentary"` + + - `"final_answer"` - - `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 }` @@ -172720,58 +171906,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"` @@ -172779,301 +171980,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 }` @@ -173083,109 +172291,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 }` @@ -173195,55 +172405,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 }` @@ -173273,180 +172460,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 }` @@ -173456,354 +172623,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](https://platform.openai.com/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 array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` - - `"auto"` + Citations associated with the text content. - - `"required"` + - `array of 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. + - `array of 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](https://platform.openai.com/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](https://platform.openai.com/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"` + - `array of 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](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/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](https://platform.openai.com/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](https://platform.openai.com/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 }` @@ -174066,7 +173200,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-web-search). + [web search tool](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -174126,7 +173260,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -174178,7 +173312,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -174324,8 +173458,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`. @@ -174370,19 +173536,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `background: optional "transparent" or "opaque" or "auto"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. - - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. - - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - `"transparent"` @@ -174411,13 +173566,13 @@ curl -X POST https://api.openai.com/v1/responses/compact \ Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `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-2" or 3 more` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` The image generation model to use. Default: `gpt-image-1`. @@ -174425,14 +173580,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"gpt-image-1-mini"` - - `"gpt-image-2"` - - - `"gpt-image-2-2026-04-21"` - - `"gpt-image-1.5"` - - `"chatgpt-image-latest"` - - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -174523,13 +173672,131 @@ 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](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -174643,7 +173910,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -174811,269 +174078,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](https://platform.openai.com/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](https://platform.openai.com/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. - - `previous_response_id: optional string` + - `string` - The unique ID of the previous response to the model. Use this to - create multi-turn conversations. Learn more about - [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + - `number` - - `prompt: optional BetaResponsePrompt` + - `boolean` - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + - `array of string or number` - - `id: string` + - `string` - The unique identifier of the prompt template to use. + - `number` - - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` + - `CompoundFilter object { filters, 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. + Combine multiple filters using `and` or `or`. - - `string` + - `filters: array of object { key, type, value } or unknown` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - A text input to the model. + - `ComparisonFilter object { key, type, value }` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `key: string` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + The key to compare against the value. - A file input to the model. + - `type: "eq" or "ne" or "gt" or 5 more` - - `version: optional string` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - Optional version of the prompt template. + - `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 - - `prompt_cache_key: optional string` + - `"eq"` - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + - `"ne"` - - `prompt_cache_options: optional object { mode, ttl }` + - `"gt"` - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + - `"gte"` - - `mode: "implicit" or "explicit"` + - `"lt"` - Whether implicit prompt-cache breakpoints were enabled. + - `"lte"` - - `"implicit"` + - `"in"` - - `"explicit"` + - `"nin"` - - `ttl: "30m"` + - `value: string or number or boolean or array of string or number` - The minimum lifetime applied to each cache breakpoint. + The value to compare against the attribute key; supports string, number, or boolean types. - - `"30m"` + - `string` - - `prompt_cache_retention: optional "in_memory" or "24h"` + - `number` - Deprecated. Use `prompt_cache_options.ttl` instead. + - `boolean` - 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](https://platform.openai.com/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. + - `array of string or number` - 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. + - `number` - - `"in_memory"` + - `unknown` - - `"24h"` + - `type: "and" or "or"` - - `reasoning: optional object { context, effort, generate_summary, 2 more }` + Type of operation: `and` or `or`. - **gpt-5 and o-series models only** + - `"and"` - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + - `"or"` - - `context: optional "auto" or "current_turn" or "all_turns"` + - `max_num_results: optional number` - Controls which reasoning items are rendered back to the model on later turns. - When returned on a response, this is the effective reasoning context mode - used for the response. + 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"` - - `"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"` @@ -175081,1434 +174422,1500 @@ 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` - - `"auto"` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `"concise"` + - `region: optional string` - - `"detailed"` + Free text input for the region of the user, e.g. `California`. - - `mode: optional string or "standard" or "pro"` + - `timezone: optional string` - Controls the reasoning execution mode for the request. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - When returned on a response, this is the effective execution mode. + - `type: optional "approximate"` - - `string` + The type of location approximation. Always `approximate`. - - `"standard" or "pro"` + - `"approximate"` - Controls the reasoning execution mode for the request. + - `Mcp object { server_label, type, allowed_callers, 9 more }` - When returned on a response, this is the effective execution mode. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - - `"standard"` + - `server_label: string` - - `"pro"` + A label for this MCP server, used to identify it in tool calls. - - `summary: optional "auto" or "concise" or "detailed"` + - `type: "mcp"` - 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 type of the MCP tool. Always `mcp`. - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + - `"mcp"` - - `"auto"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"concise"` + The tool invocation context(s). - - `"detailed"` + - `"direct"` - - `safety_identifier: optional string` + - `"programmatic"` - 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](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `service_tier: optional "auto" or "default" or "flex" or 2 more` + List of allowed tool names or a filter object. - Specifies the processing type used for serving the request. + - `McpAllowedTools = 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](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. + A string array of allowed tool names - 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. + - `McpToolFilter object { read_only, tool_names }` - - `"auto"` + A filter object to specify which tools are allowed. - - `"default"` + - `read_only: optional boolean` - - `"flex"` + 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. - - `"scale"` + - `tool_names: optional array of string` - - `"priority"` + List of allowed tool names. - - `status: optional BetaResponseStatus` + - `authorization: optional string` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, 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. - - `"completed"` + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `"failed"` + 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). - - `"in_progress"` + Currently supported `connector_id` values are: - - `"cancelled"` + - 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` - - `"queued"` + - `"connector_dropbox"` - - `"incomplete"` + - `"connector_gmail"` - - `text: optional BetaResponseTextConfig` + - `"connector_googlecalendar"` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + - `"connector_googledrive"` - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `"connector_microsoftteams"` - - `format: optional BetaResponseFormatTextConfig` + - `"connector_outlookcalendar"` - An object specifying the format that the model must output. + - `"connector_outlookemail"` - Configuring `{ "type": "json_schema" }` enables Structured Outputs, - which ensures the model will match your supplied JSON schema. Learn more in the - [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `"connector_sharepoint"` - The default format is `{ "type": "text" }` with no additional options. + - `defer_loading: optional boolean` - **Not recommended for gpt-4o and newer models:** + Whether this MCP tool is deferred and discovered via tool search. - 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. + - `headers: optional map[string]` - - `Text object { type }` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - Default response format. Used to generate text responses. + - `require_approval: optional object { always, never } or "always" or "never"` - - `type: "text"` + Specify which of the MCP server's tools require approval. - The type of response format being defined. Always `text`. + - `McpToolApprovalFilter object { always, never }` - - `"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. - - `BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` + - `always: optional object { read_only, tool_names }` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + A filter object to specify which tools are allowed. - - `name: string` + - `read_only: 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. + 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. - - `schema: map[unknown]` + - `tool_names: optional array of string` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + List of allowed tool names. - - `type: "json_schema"` + - `never: optional object { read_only, tool_names }` - The type of response format being defined. Always `json_schema`. + A filter object to specify which tools are allowed. - - `"json_schema"` + - `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` - - `strict: optional boolean` + List of allowed tool names. - 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](https://platform.openai.com/docs/guides/structured-outputs). + - `McpToolApprovalSetting = "always" or "never"` - - `JSONObject object { 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. - 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"` - - `type: "json_object"` + - `"never"` - The type of response format being defined. Always `json_object`. + - `server_description: optional string` - - `"json_object"` + Optional description of the MCP server, used to provide more context. - - `verbosity: optional "low" or "medium" or "high"` + - `server_url: 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 URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `"low"` + - `tunnel_id: optional string` - - `"medium"` + 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. - - `"high"` + - `CodeInterpreter object { container, type, allowed_callers }` - - `top_logprobs: optional number` + A tool that runs Python code to help generate a response to a prompt. - 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. + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `truncation: optional "auto" or "disabled"` + 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 truncation strategy to use for the model response. + - `string` - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + 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"` - - `"disabled"` + - `file_ids: optional array of string` - - `usage: optional BetaResponseUsage` + An optional list of uploaded files to make available to your code. - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `input_tokens: number` + The memory limit for the code interpreter container. - The number of input tokens. + - `"1g"` - - `input_tokens_details: object { cache_write_tokens, cached_tokens }` + - `"4g"` - A detailed breakdown of the input tokens. + - `"16g"` - - `cache_write_tokens: number` + - `"64g"` - The number of input tokens that were written to the cache. + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `cached_tokens: number` + Network access policy for the container. - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + - `BetaContainerNetworkPolicyDisabled object { type }` - - `output_tokens: number` + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - The number of output tokens. + - `type: "code_interpreter"` - - `output_tokens_details: object { reasoning_tokens }` + The type of the code interpreter tool. Always `code_interpreter`. - A detailed breakdown of the output tokens. + - `"code_interpreter"` - - `reasoning_tokens: number` + - `allowed_callers: optional array of "direct" or "programmatic"` - The number of reasoning tokens. + The tool invocation context(s). - - `total_tokens: number` + - `"direct"` - The total number of tokens used. + - `"programmatic"` - - `user: optional string` + - `ProgrammaticToolCalling object { type }` - 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](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `type: "programmatic_tool_calling"` - - `sequence_number: number` + The type of the tool. Always `programmatic_tool_calling`. - The sequence number for this event. + - `"programmatic_tool_calling"` - - `type: "response.queued"` + - `ImageGeneration object { type, action, background, 9 more }` - The type of the event. Always 'response.queued'. + A tool that generates images using the GPT image models. - - `"response.queued"` + - `type: "image_generation"` - - `agent: optional object { agent_name }` + The type of the image generation tool. Always `image_generation`. - The agent that owns this multi-agent streaming event. + - `"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`. -### Beta Response Reasoning Summary Part Added Event + - `"generate"` -- `BetaResponseReasoningSummaryPartAddedEvent object { item_id, output_index, part, 4 more }` + - `"edit"` - Emitted when a new reasoning summary part is added. + - `"auto"` - - `item_id: string` + - `background: optional "transparent" or "opaque" or "auto"` - The ID of the item this summary part is associated with. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - - `output_index: number` + - `"transparent"` - The index of the output item this summary part is associated with. + - `"opaque"` - - `part: object { text, type }` + - `"auto"` - The summary part that was added. + - `input_fidelity: optional "high" or "low"` - - `text: 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 text of the summary part. + - `"high"` - - `type: "summary_text"` + - `"low"` - The type of the summary part. Always `summary_text`. + - `input_image_mask: optional object { file_id, image_url }` - - `"summary_text"` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `sequence_number: number` + - `file_id: optional string` - The sequence number of this event. + File ID for the mask image. - - `summary_index: number` + - `image_url: optional string` - The index of the summary part within the reasoning summary. + Base64-encoded mask image. - - `type: "response.reasoning_summary_part.added"` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - The type of the event. Always `response.reasoning_summary_part.added`. + The image generation model to use. Default: `gpt-image-1`. - - `"response.reasoning_summary_part.added"` + - `string` - - `agent: optional object { agent_name }` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - The agent that owns this multi-agent streaming event. + 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"` -### Beta Response Reasoning Summary Part Done Event + - `"gpt-image-1.5"` -- `BetaResponseReasoningSummaryPartDoneEvent object { item_id, output_index, part, 5 more }` + - `moderation: optional "auto" or "low"` - Emitted when a reasoning summary part is completed. + Moderation level for the generated image. Default: `auto`. - - `item_id: string` + - `"auto"` - The ID of the item this summary part is associated with. + - `"low"` - - `output_index: number` + - `output_compression: optional number` - The index of the output item this summary part is associated with. + Compression level for the output image. Default: 100. - - `part: object { text, type }` + - `output_format: optional "png" or "webp" or "jpeg"` - The completed summary part. + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `text: string` + - `"png"` - The text of the summary part. + - `"webp"` - - `type: "summary_text"` + - `"jpeg"` - The type of the summary part. Always `summary_text`. + - `partial_images: optional number` - - `"summary_text"` + 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 this event. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `summary_index: number` + - `"low"` - The index of the summary part within the reasoning summary. + - `"medium"` - - `type: "response.reasoning_summary_part.done"` + - `"high"` - The type of the event. Always `response.reasoning_summary_part.done`. + - `"auto"` - - `"response.reasoning_summary_part.done"` + - `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 owns this multi-agent streaming event. + - `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`. - - `status: optional "incomplete"` + - `"1024x1024"` - The completion status of the summary part. Omitted when the part completed - normally and set to `incomplete` when generation was interrupted. + - `"1024x1536"` - - `"incomplete"` + - `"1536x1024"` -### Beta Response Reasoning Summary Text Delta Event + - `"auto"` -- `BetaResponseReasoningSummaryTextDeltaEvent object { delta, item_id, output_index, 4 more }` + - `LocalShell object { type }` - Emitted when a delta is added to a reasoning summary text. + A tool that allows the model to execute shell commands in a local environment. - - `delta: string` + - `type: "local_shell"` - The text delta that was added to the summary. + The type of the local shell tool. Always `local_shell`. - - `item_id: string` + - `"local_shell"` - The ID of the item this summary text delta is associated with. + - `Shell object { type, allowed_callers, environment }` - - `output_index: number` + A tool that allows the model to execute shell commands. - The index of the output item this summary text delta is associated with. + - `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"` - - `sequence_number: number` + - `Grammar object { definition, syntax, type }` - The sequence number of this event. + A grammar defined by the user. - - `summary_index: number` + - `definition: string` - The index of the summary part within the reasoning summary. + The grammar definition. - - `type: "response.reasoning_summary_text.delta"` + - `syntax: "lark" or "regex"` - The type of the event. Always `response.reasoning_summary_text.delta`. + The syntax of the grammar definition. One of `lark` or `regex`. - - `"response.reasoning_summary_text.delta"` + - `"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"` -### Beta Response Reasoning Summary Text Done Event + - `Namespace object { description, name, tools, type }` -- `BetaResponseReasoningSummaryTextDoneEvent object { item_id, output_index, sequence_number, 4 more }` + Groups function/custom tools under a shared namespace. - Emitted when a reasoning summary text is completed. + - `description: string` - - `item_id: string` + A description of the namespace shown to the model. - The ID of the item this summary text is associated with. + - `name: string` - - `output_index: number` + The namespace name used in tool calls (for example, `crm`). - The index of the output item this summary text is associated with. + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - - `sequence_number: number` + The function/custom tools available inside this namespace. - The sequence number of this event. + - `Function object { name, type, allowed_callers, 5 more }` - - `summary_index: number` + - `name: string` - The index of the summary part within the reasoning summary. + - `type: "function"` - - `text: string` + - `"function"` - The full text of the completed reasoning summary. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `type: "response.reasoning_summary_text.done"` + The tool invocation context(s). - The type of the event. Always `response.reasoning_summary_text.done`. + - `"direct"` - - `"response.reasoning_summary_text.done"` + - `"programmatic"` - - `agent: optional object { agent_name }` + - `defer_loading: optional boolean` - The agent that owns this multi-agent streaming event. + Whether this function should be deferred and discovered via tool search. - - `agent_name: string` + - `description: optional string` - The canonical name of the agent that produced this item. + - `output_schema: optional map[unknown]` -### Beta Response Reasoning Text Delta Event + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. -- `BetaResponseReasoningTextDeltaEvent object { content_index, delta, item_id, 4 more }` + - `parameters: optional unknown` - Emitted when a delta is added to a reasoning text. + - `strict: optional boolean` - - `content_index: 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 index of the reasoning content part this delta is associated with. + - `Custom object { name, type, allowed_callers, 3 more }` - - `delta: string` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - The text delta that was added to the reasoning content. + - `name: string` - - `item_id: string` + The name of the custom tool, used to identify it in tool calls. - The ID of the item this reasoning text delta is associated with. + - `type: "custom"` - - `output_index: number` + The type of the custom tool. Always `custom`. - The index of the output item this reasoning text delta is associated with. + - `"custom"` - - `sequence_number: number` + - `allowed_callers: optional array of "direct" or "programmatic"` - The sequence number of this event. + The tool invocation context(s). - - `type: "response.reasoning_text.delta"` + - `"direct"` - The type of the event. Always `response.reasoning_text.delta`. + - `"programmatic"` - - `"response.reasoning_text.delta"` + - `defer_loading: optional boolean` - - `agent: optional object { agent_name }` + Whether this tool should be deferred and discovered via tool search. - The agent that owns this multi-agent streaming event. + - `description: optional string` - - `agent_name: string` + Optional description of the custom tool, used to provide more context. - The canonical name of the agent that produced this item. + - `format: optional object { type } or object { definition, syntax, type }` -### Beta Response Reasoning Text Done Event + The input format for the custom tool. Default is unconstrained text. -- `BetaResponseReasoningTextDoneEvent object { content_index, item_id, output_index, 4 more }` + - `Text object { type }` - Emitted when a reasoning text is completed. + Unconstrained free-form text. - - `content_index: number` + - `type: "text"` - The index of the reasoning content part. + Unconstrained text format. Always `text`. - - `item_id: string` + - `"text"` - The ID of the item this reasoning text is associated with. + - `Grammar object { definition, syntax, type }` - - `output_index: number` + A grammar defined by the user. - The index of the output item this reasoning text is associated with. + - `definition: string` - - `sequence_number: number` + The grammar definition. - The sequence number of this event. + - `syntax: "lark" or "regex"` - - `text: string` + The syntax of the grammar definition. One of `lark` or `regex`. - The full text of the completed reasoning content. + - `"lark"` - - `type: "response.reasoning_text.done"` + - `"regex"` - The type of the event. Always `response.reasoning_text.done`. + - `type: "grammar"` - - `"response.reasoning_text.done"` + Grammar format. Always `grammar`. - - `agent: optional object { agent_name }` + - `"grammar"` - The agent that owns this multi-agent streaming event. + - `type: "namespace"` - - `agent_name: string` + The type of the tool. Always `namespace`. - The canonical name of the agent that produced this item. + - `"namespace"` -### Beta Response Refusal Delta Event + - `ToolSearch object { type, description, execution, parameters }` -- `BetaResponseRefusalDeltaEvent object { content_index, delta, item_id, 4 more }` + Hosted or BYOT tool search configuration for deferred tools. - Emitted when there is a partial refusal text. + - `type: "tool_search"` - - `content_index: number` + The type of the tool. Always `tool_search`. - The index of the content part that the refusal text is added to. + - `"tool_search"` - - `delta: string` + - `description: optional string` - The refusal text that is added. + Description shown to the model for a client-executed tool search tool. - - `item_id: string` + - `execution: optional "server" or "client"` - The ID of the output item that the refusal text is added to. + Whether tool search is executed by the server or by the client. - - `output_index: number` + - `"server"` - The index of the output item that the refusal text is added to. + - `"client"` - - `sequence_number: number` + - `parameters: optional unknown` - The sequence number of this event. + Parameter schema for a client-executed tool search tool. - - `type: "response.refusal.delta"` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - The type of the event. Always `response.refusal.delta`. + 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.refusal.delta"` + - `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 owns this multi-agent streaming event. + - `"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"` -### Beta Response Refusal Done Event + - `"text"` -- `BetaResponseRefusalDoneEvent object { content_index, item_id, output_index, 4 more }` + - `"image"` - Emitted when refusal text 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 refusal text is finalized. + - `"low"` - - `item_id: string` + - `"medium"` - The ID of the output item that the refusal text is finalized. + - `"high"` - - `output_index: number` + - `user_location: optional object { type, city, country, 2 more }` - The index of the output item that the refusal text is finalized. + The user's location. - - `refusal: string` + - `type: "approximate"` - The refusal text that is finalized. + The type of location approximation. Always `approximate`. - - `sequence_number: number` + - `"approximate"` - The sequence number of this event. + - `city: optional string` - - `type: "response.refusal.done"` + Free text input for the city of the user, e.g. `San Francisco`. - The type of the event. Always `response.refusal.done`. + - `country: optional string` - - `"response.refusal.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`. -### Beta Response Status + - `ApplyPatch object { type, allowed_callers }` -- `BetaResponseStatus = "completed" or "failed" or "in_progress" or 3 more` + Allows the assistant to create, delete, or update files using unified diffs. - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + - `type: "apply_patch"` - - `"completed"` + The type of the tool. Always `apply_patch`. - - `"failed"` + - `"apply_patch"` - - `"in_progress"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"cancelled"` + The tool invocation context(s). - - `"queued"` + - `"direct"` - - `"incomplete"` + - `"programmatic"` -### Beta Response Stream Event + - `type: "additional_tools"` -- `BetaResponseStreamEvent = BetaResponseAudioDeltaEvent or BetaResponseAudioDoneEvent or BetaResponseAudioTranscriptDeltaEvent or 50 more` + The item type. Always `additional_tools`. - Emitted when there is a partial audio response. + - `"additional_tools"` - - `BetaResponseAudioDeltaEvent object { delta, sequence_number, type, agent }` + - `id: optional string` - Emitted when there is a partial audio response. + The unique ID of this additional tools item. - - `delta: string` + - `agent: optional object { agent_name }` - A chunk of Base64 encoded response audio bytes. + The agent that produced this item. - - `sequence_number: number` + - `agent_name: string` - A sequence number for this chunk of the stream response. + The canonical name of the agent that produced this item. - - `type: "response.audio.delta"` + - `Reasoning object { id, summary, type, 4 more }` - The type of the event. Always `response.audio.delta`. + 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). - - `"response.audio.delta"` + - `id: string` - - `agent: optional object { agent_name }` + The unique identifier of the reasoning content. - The agent that owns this multi-agent streaming event. + - `summary: array of object { text, type }` - - `agent_name: string` + Reasoning summary content. - The canonical name of the agent that produced this item. + - `text: string` - - `BetaResponseAudioDoneEvent object { sequence_number, type, agent }` + A summary of the reasoning output from the model so far. - Emitted when the audio response is complete. + - `type: "summary_text"` - - `sequence_number: number` + The type of the object. Always `summary_text`. - The sequence number of the delta. + - `"summary_text"` - - `type: "response.audio.done"` + - `type: "reasoning"` - The type of the event. Always `response.audio.done`. + The type of the object. Always `reasoning`. - - `"response.audio.done"` + - `"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. - - `BetaResponseAudioTranscriptDeltaEvent object { delta, sequence_number, type, agent }` + - `content: optional array of object { text, type }` - Emitted when there is a partial transcript of audio. + Reasoning text content. - - `delta: string` + - `text: string` - The partial transcript of the audio response. + The reasoning text from the model. - - `sequence_number: number` + - `type: "reasoning_text"` - The sequence number of this event. + The type of the reasoning text. Always `reasoning_text`. - - `type: "response.audio.transcript.delta"` + - `"reasoning_text"` - The type of the event. Always `response.audio.transcript.delta`. + - `encrypted_content: optional string` - - `"response.audio.transcript.delta"` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - - `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"` - - `BetaResponseAudioTranscriptDoneEvent object { sequence_number, type, agent }` + - `"incomplete"` - Emitted when the full audio transcript is completed. + - `Compaction object { encrypted_content, type, id, agent }` - - `sequence_number: number` + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). - The sequence number of this event. + - `encrypted_content: string` - - `type: "response.audio.transcript.done"` + The encrypted content of the compaction summary. - The type of the event. Always `response.audio.transcript.done`. + - `type: "compaction"` - - `"response.audio.transcript.done"` + 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 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. - - `BetaResponseCodeInterpreterCallCodeDeltaEvent object { delta, item_id, output_index, 3 more }` + - `ImageGenerationCall object { id, result, status, 2 more }` - Emitted when a partial code snippet is streamed by the code interpreter. + An image generation request made by the model. - - `delta: string` + - `id: string` - The partial code snippet being streamed by the code interpreter. + The unique ID of the image generation call. - - `item_id: string` + - `result: string` - The unique identifier of the code interpreter tool call item. + The generated image encoded in base64. - - `output_index: number` + - `status: "in_progress" or "completed" or "generating" or "failed"` - The index of the output item in the response for which the code is being streamed. + The status of the image generation call. - - `sequence_number: number` + - `"in_progress"` - The sequence number of this event, used to order streaming events. + - `"completed"` - - `type: "response.code_interpreter_call_code.delta"` + - `"generating"` - The type of the event. Always `response.code_interpreter_call_code.delta`. + - `"failed"` - - `"response.code_interpreter_call_code.delta"` + - `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. - - `BetaResponseCodeInterpreterCallCodeDoneEvent object { code, item_id, output_index, 3 more }` + - `CodeInterpreterCall object { id, code, container_id, 4 more }` - Emitted when the code snippet is finalized by the code interpreter. + A tool call to run code. + + - `id: string` + + The unique ID of the code interpreter tool call. - `code: string` - The final code snippet output by the code interpreter. + The code to run, or null if not available. - - `item_id: string` + - `container_id: string` - The unique identifier of the code interpreter tool call item. + The ID of the container used to run the code. - - `output_index: number` + - `outputs: array of object { logs, type } or object { type, url }` - The index of the output item in the response for which the code is finalized. + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `sequence_number: number` + - `Logs object { logs, type }` - The sequence number of this event, used to order streaming events. + The logs output from the code interpreter. - - `type: "response.code_interpreter_call_code.done"` + - `logs: string` - The type of the event. Always `response.code_interpreter_call_code.done`. + The logs output from the code interpreter. - - `"response.code_interpreter_call_code.done"` + - `type: "logs"` - - `agent: optional object { agent_name }` + The type of the output. Always `logs`. - The agent that owns this multi-agent streaming event. + - `"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. - - `BetaResponseCodeInterpreterCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` + - `type: "image"` - Emitted when the code interpreter call is completed. + The type of the output. Always `image`. - - `item_id: string` + - `"image"` - The unique identifier of the code interpreter tool call item. + - `url: string` - - `output_index: number` + The URL of the image output from the code interpreter. - The index of the output item in the response for which the code interpreter call is completed. + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - - `sequence_number: number` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - The sequence number of this event, used to order streaming events. + - `"in_progress"` - - `type: "response.code_interpreter_call.completed"` + - `"completed"` - The type of the event. Always `response.code_interpreter_call.completed`. + - `"incomplete"` - - `"response.code_interpreter_call.completed"` + - `"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 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. - - `BetaResponseCodeInterpreterCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` + - `LocalShellCall object { id, action, call_id, 3 more }` - Emitted when a code interpreter call is in progress. + A tool call to run a command on the local shell. - - `item_id: string` + - `id: string` - The unique identifier of the code interpreter tool call item. + The unique ID of the local shell call. - - `output_index: number` + - `action: object { command, env, type, 3 more }` - The index of the output item in the response for which the code interpreter call is in progress. + Execute a shell command on the server. - - `sequence_number: number` + - `command: array of string` - The sequence number of this event, used to order streaming events. + The command to run. - - `type: "response.code_interpreter_call.in_progress"` + - `env: map[string]` - The type of the event. Always `response.code_interpreter_call.in_progress`. + Environment variables to set for the command. - - `"response.code_interpreter_call.in_progress"` + - `type: "exec"` - - `agent: optional object { agent_name }` + The type of the local shell action. Always `exec`. - The agent that owns this multi-agent streaming event. + - `"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. - - `BetaResponseCodeInterpreterCallInterpretingEvent object { item_id, output_index, sequence_number, 2 more }` + - `user: optional string` - Emitted when the code interpreter is actively interpreting the code snippet. + Optional user to run the command as. - - `item_id: string` + - `working_directory: optional string` - The unique identifier of the code interpreter tool call item. + Optional working directory to run the command in. - - `output_index: number` + - `call_id: string` - The index of the output item in the response for which the code interpreter is interpreting code. + The unique ID of the local shell tool call generated by the model. - - `sequence_number: number` + - `status: "in_progress" or "completed" or "incomplete"` - The sequence number of this event, used to order streaming events. + The status of the local shell call. - - `type: "response.code_interpreter_call.interpreting"` + - `"in_progress"` - The type of the event. Always `response.code_interpreter_call.interpreting`. + - `"completed"` - - `"response.code_interpreter_call.interpreting"` + - `"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. - - `BetaResponseCompletedEvent object { response, sequence_number, type, agent }` - - Emitted when the model response is complete. - - - `response: BetaResponse` + - `LocalShellCallOutput object { id, output, type, 2 more }` - Properties of the completed response. + The output of a local shell tool call. - `id: string` - Unique identifier for this Response. - - - `created_at: number` - - Unix timestamp (in seconds) of when this Response was created. + The unique ID of the local shell tool call generated by the model. - - `error: BetaResponseError` + - `output: string` - An error object returned when the model fails to generate a Response. + A JSON string of the output of the local shell tool call. - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 16 more` + - `type: "local_shell_call_output"` - The error code for the response. + The type of the local shell tool call output. Always `local_shell_call_output`. - - `"server_error"` + - `"local_shell_call_output"` - - `"rate_limit_exceeded"` + - `agent: optional object { agent_name }` - - `"invalid_prompt"` + The agent that produced this item. - - `"bio_policy"` + - `agent_name: string` - - `"vector_store_timeout"` + The canonical name of the agent that produced this item. - - `"invalid_image"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"invalid_image_format"` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `"invalid_base64_image"` + - `"in_progress"` - - `"invalid_image_url"` + - `"completed"` - - `"image_too_large"` + - `"incomplete"` - - `"image_too_small"` + - `ShellCall object { action, call_id, type, 5 more }` - - `"image_parse_error"` + A tool representing a request to execute one or more shell commands. - - `"image_content_policy_violation"` + - `action: object { commands, max_output_length, timeout_ms }` - - `"invalid_image_mode"` + The shell commands and limits that describe how to run the tool call. - - `"image_file_too_large"` + - `commands: array of string` - - `"unsupported_image_media_type"` + Ordered shell commands for the execution environment to run. - - `"empty_image_file"` + - `max_output_length: optional number` - - `"failed_to_download_image"` + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - - `"image_file_not_found"` + - `timeout_ms: optional number` - - `message: string` + Maximum wall-clock time in milliseconds to allow the shell commands to run. - A human-readable description of the error. + - `call_id: string` - - `incomplete_details: object { reason }` + The unique ID of the shell tool call generated by the model. - Details about why the response is incomplete. + - `type: "shell_call"` - - `reason: optional "max_output_tokens" or "content_filter"` + The type of the item. Always `shell_call`. - The reason why the response is incomplete. + - `"shell_call"` - - `"max_output_tokens"` + - `id: optional string` - - `"content_filter"` + The unique ID of the shell tool call. Populated when this item is returned via API. - - `instructions: string or array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + - `agent: optional object { agent_name }` - A system (or developer) message inserted into the model's context. + The agent that produced this item. - 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_name: string` - - `string` + The canonical name of the agent that produced this item. - A text input to the model, equivalent to a text input with the - `developer` 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. + - `environment: optional BetaLocalEnvironment or BetaContainerReference` - - `text: string` + The environment to execute the shell commands in. - The text input to the model. + - `BetaLocalEnvironment object { type, skills }` - - `type: "input_text"` + - `BetaContainerReference object { container_id, type }` - The type of the input item. Always `input_text`. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"input_text"` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `prompt_cache_breakpoint: optional object { mode }` + - `"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. + - `"completed"` - - `mode: "explicit"` + - `"incomplete"` - The breakpoint mode. Always `explicit`. + - `ShellCallOutput object { call_id, output, type, 5 more }` - - `"explicit"` + The streamed output items emitted by a shell tool call. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `call_id: string` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The unique ID of the shell tool call generated by the model. - - `detail: "low" or "high" or "auto" or "original"` + - `output: array of BetaResponseFunctionShellCallOutputContent` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + Captured chunks of stdout and stderr output, along with their associated outcomes. - - `"low"` + - `outcome: object { type } or object { exit_code, type }` - - `"high"` + The exit or timeout outcome associated with this shell call. - - `"auto"` + - `Timeout object { type }` - - `"original"` + 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"` - - `file_id: optional string` + - `Exit object { exit_code, type }` - The ID of the file to be sent to the model. + Indicates that the shell commands finished and returned an exit code. - - `image_url: optional string` + - `exit_code: number` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + The exit code returned by the shell process. - - `prompt_cache_breakpoint: optional object { mode }` + - `type: "exit"` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The outcome type. Always `exit`. - - `mode: "explicit"` + - `"exit"` - The breakpoint mode. Always `explicit`. + - `stderr: string` - - `"explicit"` + Captured stderr output for the shell call. - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `stdout: string` - A file input to the model. + Captured stdout output for the shell call. - - `type: "input_file"` + - `type: "shell_call_output"` - The type of the input item. Always `input_file`. + The type of the item. Always `shell_call_output`. - - `"input_file"` + - `"shell_call_output"` - - `detail: optional "auto" or "low" or "high"` + - `id: optional 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 unique ID of the shell tool call output. Populated when this item is returned via API. - - `"auto"` + - `agent: optional object { agent_name }` - - `"low"` + The agent that produced this item. - - `"high"` + - `agent_name: string` - - `file_data: optional string` + The canonical name of the agent that produced this item. - The content of the file to be sent to the model. + - `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 }` - - `file_url: optional string` + - `type: "direct"` - The URL of the file to be sent to the model. + The caller type. Always `direct`. - - `filename: optional string` + - `"direct"` - The name of the file to be sent to the model. + - `Program object { caller_id, type }` - - `prompt_cache_breakpoint: optional object { mode }` + - `caller_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 call ID of the program item that produced this tool call. - - `mode: "explicit"` + - `type: "program"` - The breakpoint mode. Always `explicit`. + The caller type. Always `program`. - - `"explicit"` + - `"program"` - - `role: "user" or "assistant" or "system" or "developer"` + - `max_output_length: optional number` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + The maximum number of UTF-8 characters captured for this shell call's combined output. - - `"user"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"assistant"` + The status of the shell call output. - - `"system"` + - `"in_progress"` - - `"developer"` + - `"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. + - `ApplyPatchCall object { call_id, operation, status, 4 more }` - - `"commentary"` + A tool call representing a request to create, delete, or update files using diff patches. - - `"final_answer"` + - `call_id: string` - - `type: optional "message"` + The unique ID of the apply patch tool call generated by the model. - The type of the message input. Always `message`. + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - - `"message"` + The specific create, delete, or update instruction for the apply_patch tool call. - - `Message object { content, role, agent, 2 more }` + - `CreateFile object { diff, path, 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. + Instruction for creating a new file via the apply_patch tool. - - `content: BetaResponseInputMessageContentList` + - `diff: string` - A list of one or many input items to the model, containing different content - types. + Unified diff content to apply when creating the file. - - `role: "user" or "system" or "developer"` + - `path: string` - The role of the message input. One of `user`, `system`, or `developer`. + Path of the file to create relative to the workspace root. - - `"user"` + - `type: "create_file"` - - `"system"` + The operation type. Always `create_file`. - - `"developer"` + - `"create_file"` - - `agent: optional object { agent_name }` + - `DeleteFile object { path, type }` - The agent that produced this item. + Instruction for deleting an existing file via the apply_patch tool. - - `agent_name: string` + - `path: string` - The canonical name of the agent that produced this item. + Path of the file to delete relative to the workspace root. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `type: "delete_file"` - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The operation type. Always `delete_file`. - - `"in_progress"` + - `"delete_file"` - - `"completed"` + - `UpdateFile object { diff, path, type }` - - `"incomplete"` + Instruction for updating an existing file via the apply_patch tool. - - `type: optional "message"` + - `diff: string` - The type of the message input. Always set to `message`. + Unified diff content to apply to the existing file. - - `"message"` + - `path: string` - - `BetaResponseOutputMessage object { id, content, role, 4 more }` + Path of the file to update relative to the workspace root. - An output message from the model. + - `type: "update_file"` - - `id: string` + The operation type. Always `update_file`. - The unique ID of the output message. + - `"update_file"` - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + - `status: "in_progress" or "completed"` - The content of the output message. + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `BetaResponseOutputText object { annotations, text, type, logprobs }` + - `"in_progress"` - A text output from the model. + - `"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 }` + - `type: "apply_patch_call"` - The annotations of the text output. + The type of the item. Always `apply_patch_call`. - - `FileCitation object { file_id, filename, index, type }` + - `"apply_patch_call"` - A citation to a file. + - `id: optional string` - - `file_id: string` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - 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. + - `caller: optional object { type } or object { caller_id, type }` - - `type: "file_citation"` + The execution context that produced this tool call. - The type of the file citation. Always `file_citation`. + - `Direct object { type }` - - `"file_citation"` + - `type: "direct"` - - `URLCitation object { end_index, start_index, title, 2 more }` + The caller type. Always `direct`. - A citation for a web resource used to generate a model response. + - `"direct"` - - `end_index: number` + - `Program object { caller_id, type }` - The index of the last character of the URL citation in the message. + - `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 URL citation in the message. + - `type: "program"` - - `title: string` + The caller type. Always `program`. - The title of the web resource. + - `"program"` - - `type: "url_citation"` + - `ApplyPatchCallOutput object { call_id, status, type, 4 more }` - The type of the URL citation. Always `url_citation`. + The streamed output emitted by an apply patch tool call. - - `"url_citation"` + - `call_id: string` - - `url: string` + The unique ID of the apply patch tool call generated by the model. - The URL of the web resource. + - `status: "completed" or "failed"` - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + The status of the apply patch tool call output. One of `completed` or `failed`. - A citation for a container file used to generate a model response. + - `"completed"` - - `container_id: string` + - `"failed"` - The ID of the container file. + - `type: "apply_patch_call_output"` - - `end_index: number` + The type of the item. Always `apply_patch_call_output`. - The index of the last character of the container file citation in the message. + - `"apply_patch_call_output"` - - `file_id: string` + - `id: optional string` - The ID of the file. + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `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"` + - `caller: optional object { type } or object { caller_id, type }` - The type of the container file citation. Always `container_file_citation`. + The execution context that produced this tool call. - - `"container_file_citation"` + - `Direct object { type }` - - `FilePath object { file_id, index, type }` + - `type: "direct"` - A path to a file. + The caller type. Always `direct`. - - `file_id: string` + - `"direct"` - The ID of the file. + - `Program object { caller_id, type }` - - `index: number` + - `caller_id: string` - The index of the file in the list of files. + The call ID of the program item that produced this tool call. - - `type: "file_path"` + - `type: "program"` - The type of the file path. Always `file_path`. + The caller type. Always `program`. - - `"file_path"` + - `"program"` - - `text: string` + - `output: optional string` - The text output from the model. + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - - `type: "output_text"` + - `McpListTools object { id, server_label, tools, 3 more }` - The type of the output text. Always `output_text`. + A list of tools available on an MCP server. - - `"output_text"` + - `id: string` - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + The unique ID of the list. - - `token: string` + - `server_label: string` - - `bytes: array of number` + The label of the MCP server. - - `logprob: number` + - `tools: array of object { input_schema, name, annotations, description }` - - `top_logprobs: array of object { token, bytes, logprob }` + The tools available on the server. - - `token: string` + - `input_schema: unknown` - - `bytes: array of number` + The JSON schema describing the tool's input. - - `logprob: number` + - `name: string` - - `BetaResponseOutputRefusal object { refusal, type }` + The name of the tool. - A refusal from the model. + - `annotations: optional unknown` - - `refusal: string` + Additional annotations about the tool. - The refusal explanation from the model. + - `description: optional string` - - `type: "refusal"` + The description of the tool. - The type of the refusal. Always `refusal`. + - `type: "mcp_list_tools"` - - `"refusal"` + The type of the item. Always `mcp_list_tools`. - - `role: "assistant"` + - `"mcp_list_tools"` - The role of the output message. Always `assistant`. + - `agent: optional object { agent_name }` - - `"assistant"` + The agent that produced this item. - - `status: "in_progress" or "completed" or "incomplete"` + - `agent_name: string` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + The canonical name of the agent that produced this item. - - `"in_progress"` + - `error: optional string` - - `"completed"` + Error message if the server could not list tools. - - `"incomplete"` + - `McpApprovalRequest object { id, arguments, name, 3 more }` - - `type: "message"` + A request for human approval of a tool invocation. - The type of the output message. Always `message`. + - `id: string` - - `"message"` + The unique ID of the approval request. - - `agent: optional object { agent_name }` + - `arguments: string` - The agent that produced this item. + A JSON string of arguments for the tool. - - `agent_name: string` + - `name: string` - The canonical name of the agent that produced this item. + The name of the tool to run. - - `phase: optional "commentary" or "final_answer"` + - `server_label: 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 label of the MCP server making the request. - - `"commentary"` + - `type: "mcp_approval_request"` - - `"final_answer"` + The type of the item. Always `mcp_approval_request`. - - `FileSearchCall object { id, queries, status, 3 more }` + - `"mcp_approval_request"` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `agent: optional object { agent_name }` - - `id: string` + The agent that produced this item. - The unique ID of the file search tool call. + - `agent_name: string` - - `queries: array of string` + The canonical name of the agent that produced this item. - The queries used to search for files. + - `McpApprovalResponse object { approval_request_id, approve, type, 3 more }` - - `status: "in_progress" or "searching" or "completed" or 2 more` + A response to an MCP approval request. - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `approval_request_id: string` - - `"in_progress"` + The ID of the approval request being answered. - - `"searching"` + - `approve: boolean` - - `"completed"` + Whether the request was approved. - - `"incomplete"` + - `type: "mcp_approval_response"` - - `"failed"` + The type of the item. Always `mcp_approval_response`. - - `type: "file_search_call"` + - `"mcp_approval_response"` - The type of the file search tool call. Always `file_search_call`. + - `id: optional string` - - `"file_search_call"` + The unique ID of the approval response - `agent: optional object { agent_name }` @@ -176518,73 +175925,60 @@ 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. - - - `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` + - `reason: optional string` - - `number` + Optional reason for the decision. - - `boolean` + - `McpCall object { id, arguments, name, 7 more }` - - `file_id: optional string` + An invocation of a tool on an MCP server. - The unique ID of the file. + - `id: string` - - `filename: optional string` + The unique ID of the tool call. - The name of the file. + - `arguments: string` - - `score: optional number` + A JSON string of the arguments passed to the tool. - The relevance score of the file - a value between 0 and 1. + - `name: string` - - `text: optional string` + The name of the tool that was run. - The text that was retrieved from the file. + - `server_label: string` - - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` + The label of the MCP server running the tool. - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + - `type: "mcp_call"` - - `id: string` + The type of the item. Always `mcp_call`. - The unique ID of the computer call. + - `"mcp_call"` - - `call_id: string` + - `agent: optional object { agent_name }` - An identifier used when responding to the tool call with output. + The agent that produced this item. - - `pending_safety_checks: array of object { id, code, message }` + - `agent_name: string` - The pending safety checks for the computer call. + The canonical name of the agent that produced this item. - - `id: string` + - `approval_request_id: optional string` - The ID of the pending safety check. + 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. - - `code: optional string` + - `error: optional string` - The type of the pending safety check. + The error from the tool call, if any. - - `message: optional string` + - `output: optional string` - Details about the pending safety check. + The output from the tool call. - - `status: "in_progress" or "completed" or "incomplete"` + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - `"in_progress"` @@ -176592,247 +175986,242 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"incomplete"` - - `type: "computer_call"` + - `"calling"` - The type of the computer call. Always `computer_call`. + - `"failed"` - - `"computer_call"` + - `CustomToolCallOutput object { call_id, output, type, 3 more }` - - `action: optional BetaComputerAction` + The output of a custom tool call from your code, being sent back to the model. - A click action. + - `call_id: string` - - `Click object { button, type, x, 2 more }` + The call ID, used to map this custom tool call output to a custom tool call. - A click action. + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `button: "left" or "right" or "wheel" or 2 more` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `StringOutput = string` - - `"left"` + A string of the output of the custom tool call. - - `"right"` + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `"wheel"` + Text, image, or file output of the custom tool call. - - `"back"` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `"forward"` + A text input to the model. - - `type: "click"` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - Specifies the event type. For a click action, this property is always `click`. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `"click"` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `x: number` + A file input to the model. - The x-coordinate where the click occurred. + - `type: "custom_tool_call_output"` - - `y: number` + The type of the custom tool call output. Always `custom_tool_call_output`. - The y-coordinate where the click occurred. + - `"custom_tool_call_output"` - - `keys: optional array of string` + - `id: optional string` - The keys being held while clicking. + The unique ID of the custom tool call output in the OpenAI platform. - - `DoubleClick object { keys, type, x, y }` + - `agent: optional object { agent_name }` - A double click action. + The agent that produced this item. - - `keys: array of string` + - `agent_name: string` - The keys being held while double-clicking. + The canonical name of the agent that produced this item. - - `type: "double_click"` + - `caller: optional object { type } or object { caller_id, type }` - Specifies the event type. For a double click action, this property is always set to `double_click`. + The execution context that produced this tool call. - - `"double_click"` + - `Direct object { type }` - - `x: number` + - `type: "direct"` - The x-coordinate where the double click occurred. + The caller type. Always `direct`. - - `y: number` + - `"direct"` - The y-coordinate where the double click occurred. + - `Program object { caller_id, type }` - - `Drag object { path, type, keys }` + - `caller_id: string` - A drag action. + The call ID of the program item that produced this tool call. - - `path: array of object { x, y }` + - `type: "program"` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + The caller type. Always `program`. - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `"program"` - - `x: number` + - `CustomToolCall object { call_id, input, name, 5 more }` - The x-coordinate. + A call to a custom tool created by the model. - - `y: number` + - `call_id: string` - The y-coordinate. + An identifier used to map this custom tool call to a tool call output. - - `type: "drag"` + - `input: string` - Specifies the event type. For a drag action, this property is always set to `drag`. + The input for the custom tool call generated by the model. - - `"drag"` + - `name: string` - - `keys: optional array of string` + The name of the custom tool being called. - The keys being held while dragging the mouse. + - `type: "custom_tool_call"` - - `Keypress object { keys, type }` + The type of the custom tool call. Always `custom_tool_call`. - A collection of keypresses the model would like to perform. + - `"custom_tool_call"` - - `keys: array of string` + - `id: optional string` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + The unique ID of the custom tool call in the OpenAI platform. - - `type: "keypress"` + - `agent: optional object { agent_name }` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + The agent that produced this item. - - `"keypress"` + - `agent_name: string` - - `Move object { type, x, y, keys }` + The canonical name of the agent that produced this item. - A mouse move action. + - `caller: optional object { type } or object { caller_id, type }` - - `type: "move"` + The execution context that produced this tool call. - Specifies the event type. For a move action, this property is always set to `move`. + - `Direct object { type }` - - `"move"` + - `type: "direct"` - - `x: number` + - `"direct"` - The x-coordinate to move to. + - `Program object { caller_id, type }` - - `y: number` + - `caller_id: string` - The y-coordinate to move to. + The call ID of the program item that produced this tool call. - - `keys: optional array of string` + - `type: "program"` - The keys being held while moving the mouse. + - `"program"` - - `Screenshot object { type }` + - `namespace: optional string` - A screenshot action. + The namespace of the custom tool being called. - - `type: "screenshot"` + - `CompactionTrigger object { type, agent }` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + Compacts the current context. Must be the final input item. - - `"screenshot"` + - `type: "compaction_trigger"` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + The type of the item. Always `compaction_trigger`. - A scroll action. + - `"compaction_trigger"` - - `scroll_x: number` + - `agent: optional object { agent_name }` - The horizontal scroll distance. + The agent that produced this item. - - `scroll_y: number` + - `agent_name: string` - The vertical scroll distance. + The canonical name of the agent that produced this item. - - `type: "scroll"` + - `ItemReference object { id, agent, type }` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + An internal identifier for an item to reference. - - `"scroll"` + - `id: string` - - `x: number` + The ID of the item to reference. - The x-coordinate where the scroll occurred. + - `agent: optional object { agent_name }` - - `y: number` + The agent that produced this item. - The y-coordinate where the scroll occurred. + - `agent_name: string` - - `keys: optional array of string` + The canonical name of the agent that produced this item. - The keys being held while scrolling. + - `type: optional "item_reference"` - - `Type object { text, type }` + The type of item to reference. Always `item_reference`. - An action to type in text. + - `"item_reference"` - - `text: string` + - `Program object { id, call_id, code, 3 more }` - The text to type. + - `id: string` - - `type: "type"` + The unique ID of this program item. - Specifies the event type. For a type action, this property is always set to `type`. + - `call_id: string` - - `"type"` + The stable call ID of the program item. - - `Wait object { type }` + - `code: string` - A wait action. + The JavaScript source executed by programmatic tool calling. - - `type: "wait"` + - `fingerprint: string` - Specifies the event type. For a wait action, this property is always set to `wait`. + Opaque program replay fingerprint that must be round-tripped. - - `"wait"` + - `type: "program"` - - `actions: optional BetaComputerActionList` + The item 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 }` + - `agent: optional object { agent_name }` - A click action. + 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. - - `Drag object { path, type, keys }` + - `ProgramOutput object { id, call_id, result, 3 more }` - A drag action. + - `id: string` - - `Keypress object { keys, type }` + The unique ID of this program output item. - A collection of keypresses the model would like to perform. + - `call_id: string` - - `Move object { type, x, y, keys }` + The call ID of the program item. - A mouse move action. + - `result: string` - - `Screenshot object { type }` + The result produced by the program item. - A screenshot action. + - `status: "completed" or "incomplete"` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + The terminal status of the program output. - A scroll action. + - `"completed"` - - `Type object { text, type }` + - `"incomplete"` - An action to type in text. + - `type: "program_output"` - - `Wait object { type }` + The item type. Always `program_output`. - A wait action. + - `"program_output"` - `agent: optional object { agent_name }` @@ -176842,714 +176231,794 @@ 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. - - - `call_id: string` - - The ID of the computer tool call that produced the output. + - `instructions: optional string` - - `output: BetaResponseComputerToolCallOutputScreenshot` + A system (or developer) message inserted into the model's context. - A computer screenshot image used with the computer use tool. + 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: "computer_screenshot"` + - `max_output_tokens: optional number` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + 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). - - `"computer_screenshot"` + - `max_tool_calls: optional number` - - `file_id: optional 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 identifier of an uploaded file that contains the screenshot. + - `metadata: optional map[string]` - - `image_url: 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. - The URL of the screenshot image. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `type: "computer_call_output"` + - `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 computer tool call output. Always `computer_call_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. - - `"computer_call_output"` + - `"gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more` - - `id: optional 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 ID of the computer tool call output. + - `"gpt-5.6-sol"` - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `"gpt-5.6-terra"` - The safety checks reported by the API that have been acknowledged by the developer. + - `"gpt-5.6-luna"` - - `id: string` + - `"gpt-5.4"` - The ID of the pending safety check. + - `"gpt-5.4-mini"` - - `code: optional string` + - `"gpt-5.4-nano"` - The type of the pending safety check. + - `"gpt-5.4-mini-2026-03-17"` - - `message: optional string` + - `"gpt-5.4-nano-2026-03-17"` - Details about the pending safety check. + - `"gpt-5.3-chat-latest"` - - `agent: optional object { agent_name }` + - `"gpt-5.2"` - The agent that produced this item. + - `"gpt-5.2-2025-12-11"` - - `agent_name: string` + - `"gpt-5.2-chat-latest"` - The canonical name of the agent that produced this item. + - `"gpt-5.2-pro"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"gpt-5.2-pro-2025-12-11"` - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + - `"gpt-5.1"` - - `"in_progress"` + - `"gpt-5.1-2025-11-13"` - - `"completed"` + - `"gpt-5.1-codex"` - - `"incomplete"` + - `"gpt-5.1-mini"` - - `WebSearchCall object { id, action, status, 2 more }` + - `"gpt-5.1-chat-latest"` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `"gpt-5"` - - `id: string` + - `"gpt-5-mini"` - The unique ID of the web search tool call. + - `"gpt-5-nano"` - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + - `"gpt-5-2025-08-07"` - 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-mini-2025-08-07"` - - `Search object { type, queries, query, sources }` + - `"gpt-5-nano-2025-08-07"` - Action type "search" - Performs a web search query. + - `"gpt-5-chat-latest"` - - `type: "search"` + - `"gpt-4.1"` - The action type. + - `"gpt-4.1-mini"` - - `"search"` + - `"gpt-4.1-nano"` - - `queries: optional array of string` + - `"gpt-4.1-2025-04-14"` - The search queries. + - `"gpt-4.1-mini-2025-04-14"` - - `query: optional string` + - `"gpt-4.1-nano-2025-04-14"` - The search query. + - `"o4-mini"` - - `sources: optional array of object { type, url }` + - `"o4-mini-2025-04-16"` - The sources used in the search. + - `"o3"` - - `type: "url"` + - `"o3-2025-04-16"` - The type of source. Always `url`. + - `"o3-mini"` - - `"url"` + - `"o3-mini-2025-01-31"` - - `url: string` + - `"o1"` - The URL of the source. + - `"o1-2024-12-17"` - - `OpenPage object { type, url }` + - `"o1-preview"` - Action type "open_page" - Opens a specific URL from search results. + - `"o1-preview-2024-09-12"` - - `type: "open_page"` + - `"o1-mini"` - The action type. + - `"o1-mini-2024-09-12"` - - `"open_page"` + - `"gpt-4o"` - - `url: optional string` + - `"gpt-4o-2024-11-20"` - The URL opened by the model. + - `"gpt-4o-2024-08-06"` - - `FindInPage object { pattern, type, url }` + - `"gpt-4o-2024-05-13"` - Action type "find_in_page": Searches for a pattern within a loaded page. + - `"gpt-4o-audio-preview"` - - `pattern: string` + - `"gpt-4o-audio-preview-2024-10-01"` - The pattern or text to search for within the page. + - `"gpt-4o-audio-preview-2024-12-17"` - - `type: "find_in_page"` + - `"gpt-4o-audio-preview-2025-06-03"` - The action type. + - `"gpt-4o-mini-audio-preview"` - - `"find_in_page"` + - `"gpt-4o-mini-audio-preview-2024-12-17"` - - `url: string` + - `"gpt-4o-search-preview"` - The URL of the page searched for the pattern. + - `"gpt-4o-mini-search-preview"` - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `"gpt-4o-search-preview-2025-03-11"` - The status of the web search tool call. + - `"gpt-4o-mini-search-preview-2025-03-11"` - - `"in_progress"` + - `"chatgpt-4o-latest"` - - `"searching"` + - `"codex-mini-latest"` - - `"completed"` + - `"gpt-4o-mini"` - - `"failed"` + - `"gpt-4o-mini-2024-07-18"` - - `type: "web_search_call"` + - `"gpt-4-turbo"` - The type of the web search tool call. Always `web_search_call`. + - `"gpt-4-turbo-2024-04-09"` - - `"web_search_call"` + - `"gpt-4-0125-preview"` - - `agent: optional object { agent_name }` + - `"gpt-4-turbo-preview"` - The agent that produced this item. + - `"gpt-4-1106-preview"` - - `agent_name: string` + - `"gpt-4-vision-preview"` - The canonical name of the agent that produced this item. + - `"gpt-4"` - - `FunctionCall object { arguments, call_id, name, 6 more }` + - `"gpt-4-0314"` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `"gpt-4-0613"` - - `arguments: string` + - `"gpt-4-32k"` - A JSON string of the arguments to pass to the function. + - `"gpt-4-32k-0314"` - - `call_id: string` + - `"gpt-4-32k-0613"` - The unique ID of the function tool call generated by the model. + - `"gpt-3.5-turbo"` - - `name: string` + - `"gpt-3.5-turbo-16k"` - The name of the function to run. + - `"gpt-3.5-turbo-0301"` - - `type: "function_call"` + - `"gpt-3.5-turbo-0613"` - The type of the function tool call. Always `function_call`. + - `"gpt-3.5-turbo-1106"` - - `"function_call"` + - `"gpt-3.5-turbo-0125"` - - `id: optional string` + - `"gpt-3.5-turbo-16k-0613"` - The unique ID of the function tool call. + - `"o1-pro"` - - `agent: optional object { agent_name }` + - `"o1-pro-2025-03-19"` - The agent that produced this item. + - `"o3-pro"` - - `agent_name: string` + - `"o3-pro-2025-06-10"` - The canonical name of the agent that produced this item. + - `"o3-deep-research"` - - `caller: optional object { type } or object { caller_id, type }` + - `"o3-deep-research-2025-06-26"` - The execution context that produced this tool call. + - `"o4-mini-deep-research"` - - `Direct object { type }` + - `"o4-mini-deep-research-2025-06-26"` - - `type: "direct"` + - `"computer-use-preview"` - - `"direct"` + - `"computer-use-preview-2025-03-11"` - - `Program object { caller_id, type }` + - `"gpt-5-codex"` - - `caller_id: string` + - `"gpt-5-pro"` - The call ID of the program item that produced this tool call. + - `"gpt-5-pro-2025-10-06"` - - `type: "program"` + - `"gpt-5.1-codex-max"` - - `"program"` + - `string` - - `namespace: optional string` + - `moderation: optional object { model, policy }` - The namespace of the function to run. + Configuration for running moderation on the input and output of this response. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `model: string` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The moderation model to use for moderated completions, e.g. 'omni-moderation-latest'. - - `"in_progress"` + - `policy: optional object { input, output }` - - `"completed"` + The policy to apply to moderated response input and output. - - `"incomplete"` + - `input: optional object { mode }` - - `FunctionCallOutput object { call_id, output, type, 4 more }` + The moderation policy for the response input. - The output of a function tool call. + - `mode: "score" or "block"` - - `call_id: string` + - `"score"` - The unique ID of the function tool call generated by the model. + - `"block"` - - `output: string or BetaResponseFunctionCallOutputItemList` + - `output: optional object { mode }` - Text, image, or file output of the function tool call. + The moderation policy for the response output. - - `string` + - `mode: "score" or "block"` - A JSON string of the output of the function tool call. + - `"score"` - - `BetaResponseFunctionCallOutputItemList = array of BetaResponseFunctionCallOutputItem` + - `"block"` - An array of content outputs (text, image, file) for the function tool call. + - `multi_agent: optional object { enabled, max_concurrent_subagents }` - - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` + Configuration for server-hosted multi-agent execution. - A text input to the model. + - `enabled: boolean` - - `text: string` + Whether to enable server-hosted multi-agent execution for this response. - The text input to the model. + - `max_concurrent_subagents: optional number` - - `type: "input_text"` + `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 type of the input item. Always `input_text`. + - `parallel_tool_calls: optional boolean` - - `"input_text"` + Whether to allow the model to run tool calls in parallel. - - `prompt_cache_breakpoint: optional object { mode }` + - `previous_response_id: optional string` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The unique ID of the 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`. - - `mode: "explicit"` + - `prompt: optional BetaResponsePrompt` - The breakpoint mode. Always `explicit`. + Reference to a prompt template and its variables. + [Learn more](/docs/guides/text?api-mode=responses#reusable-prompts). - - `"explicit"` + - `id: string` - - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` + The unique identifier of the prompt template to use. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` - - `type: "input_image"` + 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 type of the input item. Always `input_image`. + - `string` - - `"input_image"` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `detail: optional "low" or "high" or "auto" or "original"` + A text input to the model. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `"low"` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `"high"` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `"auto"` + A file input to the model. - - `"original"` + - `version: optional string` - - `file_id: optional string` + Optional version of the prompt template. - The ID of the file to be sent to the model. + - `prompt_cache_key: optional string` - - `image_url: 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). - 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_options: optional object { mode, ttl }` - - `prompt_cache_breakpoint: optional object { mode }` + 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. - Marks the exact end of a reusable 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: optional "implicit" or "explicit"` - - `mode: "explicit"` + 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 breakpoint mode. Always `explicit`. + - `"implicit"` - `"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"` + - `ttl: optional "30m"` - - `detail: optional "auto" or "low" or "high"` + 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 detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `"30m"` - - `"auto"` + - `prompt_cache_retention: optional "in_memory" or "24h"` - - `"low"` + Deprecated. Use `prompt_cache_options.ttl` instead. - - `"high"` + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. - - `file_data: optional string` + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - The base64-encoded data of the file to be sent to the model. + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - - `file_id: optional string` + - `"in_memory"` - The ID of the file to be sent to the model. + - `"24h"` - - `file_url: optional string` + - `reasoning: optional object { context, effort, generate_summary, 2 more }` - The URL of the file to be sent to the model. + **gpt-5 and o-series models only** - - `filename: optional string` + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - The name of the file to be sent to the model. + - `context: optional "auto" or "current_turn" or "all_turns"` - - `prompt_cache_breakpoint: optional object { mode }` + Controls which reasoning items are rendered back to the model on later turns. + When returned on a response, this is the effective reasoning context mode + used for the 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. + - `"auto"` - - `mode: "explicit"` + - `"current_turn"` - The breakpoint mode. Always `explicit`. + - `"all_turns"` - - `"explicit"` + - `effort: optional "none" or "minimal" or "low" or 4 more` - - `type: "function_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. - The type of the function tool call output. Always `function_call_output`. + - `"none"` - - `"function_call_output"` + - `"minimal"` - - `id: optional string` + - `"low"` - The unique ID of the function tool call output. Populated when this item is returned via API. + - `"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. + - `generate_summary: optional "auto" or "concise" or "detailed"` - - `caller: optional object { type } or object { caller_id, type }` + **Deprecated:** use `summary` instead. - The execution context that produced this tool 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`. - - `Direct object { type }` + - `"auto"` - - `type: "direct"` + - `"concise"` - The caller type. Always `direct`. + - `"detailed"` - - `"direct"` + - `mode: optional string or "standard" or "pro"` - - `Program object { caller_id, type }` + Controls the reasoning execution mode for the request. - - `caller_id: string` + When returned on a response, this is the effective execution mode. - The call ID of the program item that produced this tool call. + - `string` - - `type: "program"` + - `"standard" or "pro"` - The caller type. Always `program`. + Controls the reasoning execution mode for the request. - - `"program"` + When returned on a response, this is the effective execution mode. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"standard"` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + - `"pro"` - - `"in_progress"` + - `summary: optional "auto" or "concise" or "detailed"` - - `"completed"` + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - - `"incomplete"` + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - - `AgentMessage object { author, content, recipient, 3 more }` + - `"auto"` - A message routed between agents. + - `"concise"` - - `author: string` + - `"detailed"` - The sending agent identity. + - `safety_identifier: optional string` - - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, 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). - Plaintext, image, or encrypted content sent between agents. + - `service_tier: optional "auto" or "default" or "flex" or 2 more` - - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` + Specifies the processing type used for serving the request. - A text input to the model. + - 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'. - - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `"auto"` - - `EncryptedContent object { encrypted_content, type }` + - `"default"` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `"flex"` - - `encrypted_content: string` + - `"scale"` - Opaque encrypted content. + - `"priority"` - - `type: "encrypted_content"` + - `store: optional boolean` - The type of the input item. Always `encrypted_content`. + Whether to store the generated model response for later retrieval via + API. - - `"encrypted_content"` + - `stream: optional boolean` - - `recipient: 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. - The destination agent identity. + - `stream_options: optional object { include_obfuscation }` - - `type: "agent_message"` + Options for streaming responses. Only set this when you set `stream: true`. - The item type. Always `agent_message`. + - `include_obfuscation: optional boolean` - - `"agent_message"` + When true, stream obfuscation will be enabled. Stream obfuscation adds + random characters to an `obfuscation` field on streaming delta events to + normalize payload sizes as a mitigation to certain side-channel attacks. + These obfuscation fields are included by default, but add a small amount + of overhead to the data stream. You can set `include_obfuscation` to + false to optimize for bandwidth if you trust the network links between + your application and the OpenAI API. - - `id: optional string` + - `temperature: optional number` - The unique ID of this agent message item. + 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. - - `agent: optional object { agent_name }` + - `text: optional BetaResponseTextConfig` - The agent that produced this item. + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - - `agent_name: string` + - [Text inputs and outputs](/docs/guides/text) + - [Structured Outputs](/docs/guides/structured-outputs) - The canonical name of the agent that produced this item. + - `format: optional BetaResponseFormatTextConfig` - - `MultiAgentCall object { action, arguments, call_id, 3 more }` + An object specifying the format that the model must output. - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 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). - The multi-agent action that was executed. + The default format is `{ "type": "text" }` with no additional options. - - `"spawn_agent"` + **Not recommended for gpt-4o and newer models:** - - `"interrupt_agent"` + 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. - - `"list_agents"` + - `Text object { type }` - - `"send_message"` + Default response format. Used to generate text responses. - - `"followup_task"` + - `type: "text"` - - `"wait_agent"` + The type of response format being defined. Always `text`. - - `arguments: string` + - `"text"` - The action arguments as a JSON string. + - `BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` - - `call_id: string` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - The unique ID linking this call to its output. + - `name: string` - - `type: "multi_agent_call"` + 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 item type. Always `multi_agent_call`. + - `schema: map[unknown]` - - `"multi_agent_call"` + 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` + - `type: "json_schema"` - The unique ID of this multi-agent call. + The type of response format being defined. Always `json_schema`. - - `agent: optional object { agent_name }` + - `"json_schema"` - The agent that produced this item. + - `description: optional string` - - `agent_name: string` + A description of what the response format is for, used by the model to + determine how to respond in the format. - The canonical name of the agent that produced this item. + - `strict: optional boolean` - - `MultiAgentCallOutput object { action, call_id, output, 3 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). - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `JSONObject object { type }` - The multi-agent action that produced this result. + 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. - - `"spawn_agent"` + - `type: "json_object"` - - `"interrupt_agent"` + The type of response format being defined. Always `json_object`. - - `"list_agents"` + - `"json_object"` - - `"send_message"` + - `verbosity: optional "low" or "medium" or "high"` - - `"followup_task"` + 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`. - - `"wait_agent"` + - `"low"` - - `call_id: string` + - `"medium"` - The unique ID of the multi-agent call. + - `"high"` - - `output: array of object { text, type, annotations }` + - `tool_choice: optional BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` - Text output returned by the multi-agent action. + 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: string` + - `BetaToolChoiceOptions = "none" or "auto" or "required"` - The text content. + Controls which (if any) tool is called by the model. - - `type: "output_text"` + `none` means the model will not call any tool and instead generates a message. - The content type. Always `output_text`. + `auto` means the model can pick between generating a message or calling one or + more tools. - - `"output_text"` + `required` means the model must call one or more tools. - - `annotations: optional array of object { file_id, filename, index, type } or array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` + - `"none"` - Citations associated with the text content. + - `"auto"` - - `array of object { file_id, filename, index, type }` + - `"required"` - - `file_id: string` + - `BetaToolChoiceAllowed object { mode, tools, type }` - The ID of the file. + Constrains the tools available to the model to a pre-defined set. - - `filename: string` + - `mode: "auto" or "required"` - The filename of the file cited. + Constrains the tools available to the model to a pre-defined set. - - `index: number` + `auto` allows the model to pick from among the allowed tools and generate a + message. - The index of the file in the list of files. + `required` requires the model to call one or more of the allowed tools. - - `type: "file_citation"` + - `"auto"` - The citation type. Always `file_citation`. + - `"required"` - - `"file_citation"` + - `tools: array of map[unknown]` - - `array of object { end_index, start_index, title, 2 more }` + A list of tool definitions that the model should be allowed to call. - - `end_index: number` + For the Responses API, the list of tool definitions might look like: - The index of the last character of the citation in the message. + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - - `start_index: number` + - `type: "allowed_tools"` - The index of the first character of the citation in the message. + Allowed tool configuration type. Always `allowed_tools`. - - `title: string` + - `"allowed_tools"` - The title of the cited resource. + - `BetaToolChoiceTypes object { type }` - - `type: "url_citation"` + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](/docs/guides/tools). - The citation type. Always `url_citation`. + - `type: "file_search" or "web_search_preview" or "computer" or 5 more` - - `"url_citation"` + The type of hosted tool the model should to use. Learn more about + [built-in tools](/docs/guides/tools). - - `url: string` + Allowed values are: - The URL of the cited resource. + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - - `array of object { container_id, end_index, file_id, 3 more }` + - `"file_search"` - - `container_id: string` + - `"web_search_preview"` - The ID of the container. + - `"computer"` - - `end_index: number` + - `"computer_use_preview"` - The index of the last character of the citation in the message. + - `"computer_use"` - - `file_id: string` + - `"web_search_preview_2025_03_11"` - The ID of the container file. + - `"image_generation"` - - `filename: string` + - `"code_interpreter"` - The filename of the container file cited. + - `BetaToolChoiceFunction object { name, type }` - - `start_index: number` + Use this option to force the model to call a specific function. - The index of the first character of the citation in the message. + - `name: string` - - `type: "container_file_citation"` + The name of the function to call. - The citation type. Always `container_file_citation`. + - `type: "function"` - - `"container_file_citation"` + For function calling, the type is always `function`. - - `type: "multi_agent_call_output"` + - `"function"` - The item type. Always `multi_agent_call_output`. + - `BetaToolChoiceMcp object { server_label, type, name }` - - `"multi_agent_call_output"` + 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 this multi-agent call output. + 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` - - `ToolSearchCall object { arguments, type, id, 4 more }` + The name of the tool to call on the server. - - `arguments: unknown` + - `BetaToolChoiceCustom object { name, type }` - The arguments supplied to the tool search call. + Use this option to force the model to call a specific custom tool. - - `type: "tool_search_call"` + - `name: string` - The item type. Always `tool_search_call`. + The name of the custom tool to call. - - `"tool_search_call"` + - `type: "custom"` - - `id: optional string` + For custom tool calling, the type is always `custom`. - The unique ID of this tool search 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"` - - `call_id: optional string` + - `BetaToolChoiceApplyPatch object { type }` - The unique ID of the tool search call generated by the model. + Forces the model to call the apply_patch tool when executing a tool call. - - `execution: optional "server" or "client"` + - `type: "apply_patch"` - Whether tool search was executed by the server or by the client. + The tool to call. Always `apply_patch`. - - `"server"` + - `"apply_patch"` - - `"client"` + - `BetaToolChoiceShell object { type }` - - `status: optional "in_progress" or "completed" or "incomplete"` + Forces the model to call the shell tool when a tool call is required. - The status of the tool search call. + - `type: "shell"` - - `"in_progress"` + The tool to call. Always `shell`. - - `"completed"` + - `"shell"` - - `"incomplete"` + - `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` - - `ToolSearchOutput object { tools, type, id, 4 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. - - `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: - The loaded tool definitions returned by the tool search output. + - **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 }` @@ -177812,7 +177281,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-web-search). + [web search tool](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -177872,7 +177341,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -177924,7 +177393,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -178070,40 +177539,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`. @@ -178148,19 +177585,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `background: optional "transparent" or "opaque" or "auto"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. - - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. - - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - `"transparent"` @@ -178189,13 +177615,13 @@ curl -X POST https://api.openai.com/v1/responses/compact \ Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `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-2" or 3 more` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` The image generation model to use. Default: `gpt-image-1`. @@ -178203,14 +177629,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"gpt-image-1-mini"` - - `"gpt-image-2"` - - - `"gpt-image-2-2026-04-21"` - - `"gpt-image-1.5"` - - `"chatgpt-image-latest"` - - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -178301,131 +177721,13 @@ 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](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -178539,7 +177841,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -178707,15 +178009,808 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"programmatic"` - - `type: "tool_search_output"` + - `top_logprobs: optional number` - The item type. Always `tool_search_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. - - `"tool_search_output"` + - `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: 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"` + + - `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). + + - `BetaResponseInjectEvent object { input, response_id, type }` + + 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. + + - `input: array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + + Input items to inject into the active response. + + - `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. + + - `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"` + + - `"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 item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: optional "message"` + + The type of the message input. Always set to `message`. + + - `"message"` + + - `BetaResponseOutputMessage object { id, content, role, 4 more }` + + An output message from the model. + + - `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. + + - `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. + + - `actions: optional BetaComputerActionList` + + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. + + - `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_call_output"` + + The type of the computer tool call output. Always `computer_call_output`. + + - `"computer_call_output"` - `id: optional string` - The unique ID of this tool search output. + 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. + + - `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 }` + + 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 array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` + + Citations associated with the text content. + + - `array of 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"` + + - `array of 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. + + - `array of 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 }` @@ -178739,7 +178834,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `status: optional "in_progress" or "completed" or "incomplete"` - The status of the tool search output. + The status of the tool search call. - `"in_progress"` @@ -178747,17 +178842,11 @@ 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"` + - `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` - A list of additional tools made available at this item. + The loaded tool definitions returned by the tool search output. - `Function object { name, parameters, strict, 5 more }` @@ -179020,7 +179109,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-web-search). + [web search tool](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -179080,7 +179169,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -179132,7 +179221,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -179324,19 +179413,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `background: optional "transparent" or "opaque" or "auto"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. - - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. - - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - `"transparent"` @@ -179365,13 +179443,13 @@ curl -X POST https://api.openai.com/v1/responses/compact \ Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `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-2" or 3 more` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` The image generation model to use. Default: `gpt-image-1`. @@ -179379,14 +179457,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"gpt-image-1-mini"` - - `"gpt-image-2"` - - - `"gpt-image-2-2026-04-21"` - - `"gpt-image-1.5"` - - `"chatgpt-image-latest"` - - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -179483,7 +179555,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -179597,7 +179669,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -179765,54 +179837,15 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"programmatic"` - - `type: "additional_tools"` + - `type: "tool_search_output"` - The item type. Always `additional_tools`. + The item type. Always `tool_search_output`. - - `"additional_tools"` + - `"tool_search_output"` - `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](https://platform.openai.com/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"` + The unique ID of this tool search output. - `agent: optional object { agent_name }` @@ -179822,29 +179855,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 - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `"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"` @@ -179852,1300 +179877,1226 @@ 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](https://platform.openai.com/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` + - `AdditionalTools object { role, tools, type, 2 more }` - The URL of the image output from the code interpreter. + - `role: "developer"` - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + The role that provided the additional tools. Only `developer` is supported. - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `"developer"` - - `"in_progress"` + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - - `"completed"` + A list of additional tools made available at this item. - - `"incomplete"` + - `Function object { name, parameters, strict, 5 more }` - - `"interpreting"` + 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). - - `"failed"` + - `name: string` - - `type: "code_interpreter_call"` + The name of the function to call. - The type of the code interpreter tool call. Always `code_interpreter_call`. + - `parameters: map[unknown]` - - `"code_interpreter_call"` + A JSON schema object describing the parameters of the function. - - `agent: optional object { agent_name }` + - `strict: boolean` - The agent that produced this item. + 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`. - - `LocalShellCall object { id, action, call_id, 3 more }` + - `"function"` - A tool call to run a command on the local shell. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `id: string` + The tool invocation context(s). - The unique ID of the local shell call. + - `"direct"` - - `action: object { command, env, type, 3 more }` + - `"programmatic"` - Execute a shell command on the server. + - `defer_loading: optional boolean` - - `command: array of string` + Whether this function is deferred and loaded via tool search. - The command to run. + - `description: optional string` - - `env: map[string]` + A description of the function. Used by the model to determine whether or not to call the function. - Environment variables to set for the command. + - `output_schema: optional map[unknown]` - - `type: "exec"` + A JSON schema object describing the JSON value encoded in string outputs for this function. - The type of the local shell action. Always `exec`. + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - - `"exec"` + 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). - - `timeout_ms: optional number` + - `type: "file_search"` - Optional timeout in milliseconds for the command. + The type of the file search tool. Always `file_search`. - - `user: optional string` + - `"file_search"` - Optional user to run the command as. + - `vector_store_ids: array of string` - - `working_directory: optional string` + The IDs of the vector stores to search. - Optional working directory to run the command in. + - `filters: optional object { key, type, value } or object { filters, type }` - - `call_id: string` + A filter to apply. - The unique ID of the local shell tool call generated by the model. + - `ComparisonFilter object { key, type, value }` - - `status: "in_progress" or "completed" or "incomplete"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The status of the local shell call. + - `key: string` - - `"in_progress"` + The key to compare against the value. - - `"completed"` + - `type: "eq" or "ne" or "gt" or 5 more` - - `"incomplete"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `type: "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 - The type of the local shell call. Always `local_shell_call`. + - `"eq"` - - `"local_shell_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"` - - `LocalShellCallOutput object { id, output, type, 2 more }` + - `"in"` - The output of a local shell tool call. + - `"nin"` - - `id: string` + - `value: string or number or boolean or array of string or number` - The unique ID of the local shell tool call generated by the model. + The value to compare against the attribute key; supports string, number, or boolean types. - - `output: string` + - `string` - A JSON string of the output of the local shell tool call. + - `number` - - `type: "local_shell_call_output"` + - `boolean` - The type of the local shell tool call output. Always `local_shell_call_output`. + - `array of string or number` - - `"local_shell_call_output"` + - `string` - - `agent: optional object { agent_name }` + - `number` - The agent that produced this item. + - `CompoundFilter object { filters, type }` - - `agent_name: string` + Combine multiple filters using `and` or `or`. - The canonical name of the agent that produced this item. + - `filters: array of object { key, type, value } or unknown` - - `status: optional "in_progress" or "completed" or "incomplete"` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `ComparisonFilter object { key, type, value }` - - `"in_progress"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `"completed"` + - `key: string` - - `"incomplete"` + The key to compare against the value. - - `ShellCall object { action, call_id, type, 5 more }` + - `type: "eq" or "ne" or "gt" or 5 more` - A tool representing a request to execute one or more shell commands. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `action: object { commands, max_output_length, timeout_ms }` + - `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 shell commands and limits that describe how to run the tool call. + - `"eq"` - - `commands: array of string` + - `"ne"` - Ordered shell commands for the execution environment to run. + - `"gt"` - - `max_output_length: optional number` + - `"gte"` - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + - `"lt"` - - `timeout_ms: optional number` + - `"lte"` - Maximum wall-clock time in milliseconds to allow the shell commands to run. + - `"in"` - - `call_id: string` + - `"nin"` - The unique ID of the shell tool call generated by the model. + - `value: string or number or boolean or array of string or number` - - `type: "shell_call"` + The value to compare against the attribute key; supports string, number, or boolean types. - The type of the item. Always `shell_call`. + - `string` - - `"shell_call"` + - `number` - - `id: optional string` + - `boolean` - The unique ID of the shell tool call. Populated when this item is returned via API. + - `array of string or number` - - `agent: optional object { agent_name }` + - `string` - The agent that produced this item. + - `number` - - `agent_name: string` + - `unknown` - The canonical name of the agent that produced this item. + - `type: "and" or "or"` - - `caller: optional object { type } or object { caller_id, type }` + Type of operation: `and` or `or`. - The execution context that produced this tool call. + - `"and"` - - `Direct object { type }` + - `"or"` - - `type: "direct"` + - `max_num_results: optional number` - The caller type. Always `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` - The caller type. Always `program`. + The weight of the embedding in the reciprocal ranking fusion. - - `"program"` + - `text_weight: number` - - `environment: optional BetaLocalEnvironment or BetaContainerReference` + The weight of the text in the reciprocal ranking fusion. - The environment to execute the shell commands in. + - `ranker: optional "auto" or "default-2024-11-15"` - - `BetaLocalEnvironment object { type, skills }` + The ranker to use for the file search. - - `BetaContainerReference object { container_id, type }` + - `"auto"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"default-2024-11-15"` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `score_threshold: optional number` - - `"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. - - `"completed"` + - `Computer object { type }` - - `"incomplete"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `ShellCallOutput object { call_id, output, type, 5 more }` + - `type: "computer"` - The streamed output items emitted by a shell tool call. + The type of the computer tool. Always `computer`. - - `call_id: string` + - `"computer"` - The unique ID of the shell tool call generated by the model. + - `ComputerUsePreview object { display_height, display_width, environment, type }` - - `output: array of BetaResponseFunctionShellCallOutputContent` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - Captured chunks of stdout and stderr output, along with their associated outcomes. + - `display_height: number` - - `outcome: object { type } or object { exit_code, type }` + The height of the computer display. - The exit or timeout outcome associated with this shell call. + - `display_width: number` - - `Timeout object { type }` + The width of the computer display. - Indicates that the shell call exceeded its configured time limit. + - `environment: "windows" or "mac" or "linux" or 2 more` - - `type: "timeout"` + The type of computer environment to control. - The outcome type. Always `timeout`. + - `"windows"` - - `"timeout"` + - `"mac"` - - `Exit object { exit_code, type }` + - `"linux"` - Indicates that the shell commands finished and returned an exit code. + - `"ubuntu"` - - `exit_code: number` + - `"browser"` - The exit code returned by the shell process. + - `type: "computer_use_preview"` - - `type: "exit"` + The type of the computer use tool. Always `computer_use_preview`. - The outcome type. Always `exit`. + - `"computer_use_preview"` - - `"exit"` + - `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`. + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `"program"` + - `type: "code_interpreter"` - - `output: optional string` + The type of the code interpreter tool. Always `code_interpreter`. - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + - `"code_interpreter"` - - `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. + - `"programmatic"` - - `server_label: string` + - `ProgrammaticToolCalling object { type }` - The label of the MCP server. + - `type: "programmatic_tool_calling"` - - `tools: array of object { input_schema, name, annotations, description }` + The type of the tool. Always `programmatic_tool_calling`. - The tools available on the server. + - `"programmatic_tool_calling"` - - `input_schema: unknown` + - `ImageGeneration object { type, action, background, 9 more }` - The JSON schema describing the tool's input. + A tool that generates images using the GPT image models. - - `name: string` + - `type: "image_generation"` - The name of the tool. + The type of the image generation tool. Always `image_generation`. - - `annotations: optional unknown` + - `"image_generation"` - Additional annotations about the tool. + - `action: optional "generate" or "edit" or "auto"` - - `description: optional string` + Whether to generate a new image or edit an existing image. Default: `auto`. - The description of the tool. + - `"generate"` - - `type: "mcp_list_tools"` + - `"edit"` - The type of the item. Always `mcp_list_tools`. + - `"auto"` - - `"mcp_list_tools"` + - `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"` - - `error: optional string` + - `input_fidelity: optional "high" or "low"` - Error message if the server could not list tools. + 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`. - - `McpApprovalRequest object { id, arguments, name, 3 more }` + - `"high"` - A request for human approval of a tool invocation. + - `"low"` - - `id: string` + - `input_image_mask: optional object { file_id, image_url }` - The unique ID of the approval request. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `arguments: string` + - `file_id: optional string` - A JSON string of arguments for the tool. + File ID for the mask image. - - `name: string` + - `image_url: optional string` - The name of the tool to run. + 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 making the request. + The image generation model to use. Default: `gpt-image-1`. - - `type: "mcp_approval_request"` + - `string` - The type of the item. Always `mcp_approval_request`. + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `"mcp_approval_request"` + The image generation model to use. Default: `gpt-image-1`. - - `agent: optional object { agent_name }` + - `"gpt-image-1"` - The agent that produced this item. + - `"gpt-image-1-mini"` - - `agent_name: string` + - `"gpt-image-1.5"` - The canonical name of the agent that produced this item. + - `moderation: optional "auto" or "low"` - - `McpApprovalResponse object { approval_request_id, approve, type, 3 more }` + Moderation level for the generated image. Default: `auto`. - A response to an MCP approval request. + - `"auto"` - - `approval_request_id: string` + - `"low"` - The ID of the approval request being answered. + - `output_compression: optional number` - - `approve: boolean` + Compression level for the output image. Default: 100. - Whether the request was approved. + - `output_format: optional "png" or "webp" or "jpeg"` - - `type: "mcp_approval_response"` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - The type of the item. Always `mcp_approval_response`. + - `"png"` - - `"mcp_approval_response"` + - `"webp"` - - `id: optional string` + - `"jpeg"` - The unique ID of the approval response + - `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"` - - `reason: optional string` + - `"medium"` - Optional reason for the decision. + - `"high"` - - `McpCall object { id, arguments, name, 7 more }` + - `"auto"` - An invocation of a tool on an MCP server. + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `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 unique ID of the tool call. + - `string` - - `arguments: string` + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - A JSON string of the arguments passed to 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`. - - `name: string` + - `"1024x1024"` - The name of the tool that was run. + - `"1024x1536"` - - `server_label: string` + - `"1536x1024"` - The label of the MCP server running the tool. + - `"auto"` - - `type: "mcp_call"` + - `LocalShell object { type }` - The type of the item. Always `mcp_call`. + A tool that allows the model to execute shell commands in a local environment. - - `"mcp_call"` + - `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. - - `approval_request_id: optional string` + - `type: "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. + The type of the shell tool. Always `shell`. - - `error: optional string` + - `"shell"` - 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`. + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - `"in_progress"` + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - - `"completed"` + - `BetaLocalEnvironment object { type, skills }` - - `"incomplete"` + - `BetaContainerReference object { container_id, type }` - - `"calling"` + - `Custom object { name, type, allowed_callers, 3 more }` - - `"failed"` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `CustomToolCallOutput object { call_id, output, type, 3 more }` + - `name: string` - The output of a custom tool call from your code, being sent back to the model. + The name of the custom tool, used to identify it in tool calls. - - `call_id: string` + - `type: "custom"` - The call ID, used to map this custom tool call output to a custom tool call. + The type of the custom tool. Always `custom`. - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `"custom"` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `StringOutput = string` + The tool invocation context(s). - A string of the output of the custom tool call. + - `"direct"` - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `"programmatic"` - Text, image, or file output of the custom tool call. + - `defer_loading: optional boolean` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + Whether this tool should be deferred and discovered via tool search. - A text input to the model. + - `description: optional string` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + Optional description of the custom tool, used to provide more context. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `format: optional object { type } or object { definition, syntax, type }` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + The input format for the custom tool. Default is unconstrained text. - A file input to the model. + - `Text object { type }` - - `type: "custom_tool_call_output"` + Unconstrained free-form text. - The type of the custom tool call output. Always `custom_tool_call_output`. + - `type: "text"` - - `"custom_tool_call_output"` + Unconstrained text format. Always `text`. - - `id: optional string` + - `"text"` - The unique ID of the custom tool call output in the OpenAI platform. + - `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 }` + - `Namespace object { description, name, tools, type }` - - `caller_id: string` + Groups function/custom tools under a shared namespace. - The call ID of the program item that produced this tool call. + - `description: string` - - `type: "program"` + A description of the namespace shown to the model. - The caller type. Always `program`. + - `name: string` - - `"program"` + The namespace name used in tool calls (for example, `crm`). - - `CustomToolCall object { call_id, input, name, 5 more }` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - A call to a custom tool created by the model. + The function/custom tools available inside this namespace. - - `call_id: string` + - `Function object { name, type, allowed_callers, 5 more }` - An identifier used to map this custom tool call to a tool call output. + - `name: string` - - `input: string` + - `type: "function"` - The input for the custom tool call generated by the model. + - `"function"` - - `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 function 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 }` + - `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). - - `namespace: optional string` + - `"direct"` - The namespace of the custom tool being called. + - `"programmatic"` - - `CompactionTrigger object { type, agent }` + - `defer_loading: optional boolean` - Compacts the current context. Must be the final input item. + Whether this tool should be deferred and discovered via tool search. - - `type: "compaction_trigger"` + - `description: optional string` - The type of the item. Always `compaction_trigger`. + Optional description of the custom tool, used to provide more context. - - `"compaction_trigger"` + - `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"` - - `ItemReference object { id, agent, type }` + Unconstrained text format. Always `text`. - An internal identifier for an item to reference. + - `"text"` - - `id: string` + - `Grammar object { definition, syntax, type }` - The ID of the item to reference. + 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`. - - `type: optional "item_reference"` + - `"lark"` - The type of item to reference. Always `item_reference`. + - `"regex"` - - `"item_reference"` + - `type: "grammar"` - - `Program object { id, call_id, code, 3 more }` + Grammar format. Always `grammar`. - - `id: string` + - `"grammar"` - The unique ID of this program item. + - `type: "namespace"` - - `call_id: string` + The type of the tool. Always `namespace`. - The stable call ID of the program item. + - `"namespace"` - - `code: string` + - `ToolSearch object { type, description, execution, parameters }` - The JavaScript source executed by programmatic tool calling. + Hosted or BYOT tool search configuration for deferred tools. - - `fingerprint: string` + - `type: "tool_search"` - Opaque program replay fingerprint that must be round-tripped. + The type of the tool. Always `tool_search`. - - `type: "program"` + - `"tool_search"` - The item type. Always `program`. + - `description: optional string` - - `"program"` + Description shown to the model for a client-executed tool search tool. - - `agent: optional object { agent_name }` + - `execution: optional "server" or "client"` - The agent that produced this item. + Whether tool search is executed by the server or by the client. - - `agent_name: string` + - `"server"` - The canonical name of the agent that produced this item. + - `"client"` - - `ProgramOutput object { id, call_id, result, 3 more }` + - `parameters: optional unknown` - - `id: string` + Parameter schema for a client-executed tool search tool. - The unique ID of this program output 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 call ID of the program item. + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `result: string` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - The result produced by the program item. + - `"web_search_preview"` - - `status: "completed" or "incomplete"` + - `"web_search_preview_2025_03_11"` - The terminal status of the program output. + - `search_content_types: optional array of "text" or "image"` - - `"completed"` + - `"text"` - - `"incomplete"` + - `"image"` - - `type: "program_output"` + - `search_context_size: optional "low" or "medium" or "high"` - The item type. Always `program_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. - - `"program_output"` + - `"low"` - - `agent: optional object { agent_name }` + - `"medium"` - The agent that produced this item. + - `"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. - - `metadata: map[string]` + - `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: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` + - `city: optional 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](https://platform.openai.com/docs/models) - to browse and compare available models. + Free text input for the city of the user, e.g. `San Francisco`. - - `"gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more` + - `country: optional 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](https://platform.openai.com/docs/models) - to browse and compare available models. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `"gpt-5.6-sol"` + - `region: optional string` - - `"gpt-5.6-terra"` + Free text input for the region of the user, e.g. `California`. - - `"gpt-5.6-luna"` + - `timezone: optional string` - - `"gpt-5.4"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `"gpt-5.4-mini"` + - `ApplyPatch object { type, allowed_callers }` - - `"gpt-5.4-nano"` + Allows the assistant to create, delete, or update files using unified diffs. - - `"gpt-5.4-mini-2026-03-17"` + - `type: "apply_patch"` - - `"gpt-5.4-nano-2026-03-17"` + The type of the tool. Always `apply_patch`. - - `"gpt-5.3-chat-latest"` + - `"apply_patch"` - - `"gpt-5.2"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"gpt-5.2-2025-12-11"` + The tool invocation context(s). - - `"gpt-5.2-chat-latest"` + - `"direct"` - - `"gpt-5.2-pro"` + - `"programmatic"` - - `"gpt-5.2-pro-2025-12-11"` + - `type: "additional_tools"` - - `"gpt-5.1"` + The item type. Always `additional_tools`. - - `"gpt-5.1-2025-11-13"` + - `"additional_tools"` - - `"gpt-5.1-codex"` + - `id: optional string` - - `"gpt-5.1-mini"` + The unique ID of this additional tools item. - - `"gpt-5.1-chat-latest"` + - `agent: optional object { agent_name }` - - `"gpt-5"` + The agent that produced this item. - - `"gpt-5-mini"` + - `agent_name: string` - - `"gpt-5-nano"` + The canonical name of the agent that produced this item. - - `"gpt-5-2025-08-07"` + - `Reasoning object { id, summary, type, 4 more }` - - `"gpt-5-mini-2025-08-07"` + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](/docs/guides/conversation-state). - - `"gpt-5-nano-2025-08-07"` + - `id: string` - - `"gpt-5-chat-latest"` + The unique identifier of the reasoning content. - - `"gpt-4.1"` + - `summary: array of object { text, type }` - - `"gpt-4.1-mini"` + Reasoning summary content. - - `"gpt-4.1-nano"` + - `text: string` - - `"gpt-4.1-2025-04-14"` + A summary of the reasoning output from the model so far. - - `"gpt-4.1-mini-2025-04-14"` + - `type: "summary_text"` - - `"gpt-4.1-nano-2025-04-14"` + The type of the object. Always `summary_text`. - - `"o4-mini"` + - `"summary_text"` - - `"o4-mini-2025-04-16"` + - `type: "reasoning"` - - `"o3"` + The type of the object. Always `reasoning`. - - `"o3-2025-04-16"` + - `"reasoning"` - - `"o3-mini"` + - `agent: optional object { agent_name }` - - `"o3-mini-2025-01-31"` + The agent that produced this item. - - `"o1"` + - `agent_name: string` - - `"o1-2024-12-17"` + The canonical name of the agent that produced this item. - - `"o1-preview"` + - `content: optional array of object { text, type }` - - `"o1-preview-2024-09-12"` + Reasoning text content. - - `"o1-mini"` + - `text: string` - - `"o1-mini-2024-09-12"` + The reasoning text from the model. - - `"gpt-4o"` + - `type: "reasoning_text"` - - `"gpt-4o-2024-11-20"` + The type of the reasoning text. Always `reasoning_text`. - - `"gpt-4o-2024-08-06"` + - `"reasoning_text"` - - `"gpt-4o-2024-05-13"` + - `encrypted_content: optional string` - - `"gpt-4o-audio-preview"` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - - `"gpt-4o-audio-preview-2024-10-01"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"gpt-4o-audio-preview-2024-12-17"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"gpt-4o-audio-preview-2025-06-03"` + - `"in_progress"` - - `"gpt-4o-mini-audio-preview"` + - `"completed"` - - `"gpt-4o-mini-audio-preview-2024-12-17"` + - `"incomplete"` - - `"gpt-4o-search-preview"` + - `Compaction object { encrypted_content, type, id, agent }` - - `"gpt-4o-mini-search-preview"` + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). - - `"gpt-4o-search-preview-2025-03-11"` + - `encrypted_content: string` - - `"gpt-4o-mini-search-preview-2025-03-11"` + The encrypted content of the compaction summary. - - `"chatgpt-4o-latest"` + - `type: "compaction"` - - `"codex-mini-latest"` + The type of the item. Always `compaction`. - - `"gpt-4o-mini"` + - `"compaction"` - - `"gpt-4o-mini-2024-07-18"` + - `id: optional string` - - `"gpt-4-turbo"` + The ID of the compaction item. - - `"gpt-4-turbo-2024-04-09"` + - `agent: optional object { agent_name }` - - `"gpt-4-0125-preview"` + The agent that produced this item. - - `"gpt-4-turbo-preview"` + - `agent_name: string` - - `"gpt-4-1106-preview"` + The canonical name of the agent that produced this item. - - `"gpt-4-vision-preview"` + - `ImageGenerationCall object { id, result, status, 2 more }` - - `"gpt-4"` + An image generation request made by the model. - - `"gpt-4-0314"` + - `id: string` - - `"gpt-4-0613"` + The unique ID of the image generation call. - - `"gpt-4-32k"` + - `result: string` - - `"gpt-4-32k-0314"` + The generated image encoded in base64. - - `"gpt-4-32k-0613"` + - `status: "in_progress" or "completed" or "generating" or "failed"` - - `"gpt-3.5-turbo"` + The status of the image generation call. - - `"gpt-3.5-turbo-16k"` + - `"in_progress"` - - `"gpt-3.5-turbo-0301"` + - `"completed"` - - `"gpt-3.5-turbo-0613"` + - `"generating"` - - `"gpt-3.5-turbo-1106"` + - `"failed"` - - `"gpt-3.5-turbo-0125"` + - `type: "image_generation_call"` - - `"gpt-3.5-turbo-16k-0613"` + The type of the image generation call. Always `image_generation_call`. - - `"o1-pro"` + - `"image_generation_call"` - - `"o1-pro-2025-03-19"` + - `agent: optional object { agent_name }` - - `"o3-pro"` + The agent that produced this item. - - `"o3-pro-2025-06-10"` + - `agent_name: string` - - `"o3-deep-research"` + The canonical name of the agent that produced this item. - - `"o3-deep-research-2025-06-26"` + - `CodeInterpreterCall object { id, code, container_id, 4 more }` - - `"o4-mini-deep-research"` + A tool call to run code. - - `"o4-mini-deep-research-2025-06-26"` + - `id: string` - - `"computer-use-preview"` + The unique ID of the code interpreter tool call. - - `"computer-use-preview-2025-03-11"` + - `code: string` - - `"gpt-5-codex"` + The code to run, or null if not available. - - `"gpt-5-pro"` + - `container_id: string` - - `"gpt-5-pro-2025-10-06"` + The ID of the container used to run the code. - - `"gpt-5.1-codex-max"` + - `outputs: array of object { logs, type } or object { type, url }` - - `string` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `object: "response"` + - `Logs object { logs, type }` - The object type of this resource - always set to `response`. + The logs output from the code interpreter. - - `"response"` + - `logs: string` - - `output: array of BetaResponseOutputItem` + The logs output from the code interpreter. - An array of content items generated by the model. + - `type: "logs"` - - 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 type of the output. Always `logs`. - - `BetaResponseOutputMessage object { id, content, role, 4 more }` + - `"logs"` - An output message from the model. + - `Image object { type, url }` - - `FileSearchCall object { id, queries, status, 3 more }` + The image output from the code interpreter. - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `type: "image"` - - `id: string` + The type of the output. Always `image`. - The unique ID of the file search tool call. + - `"image"` - - `queries: array of string` + - `url: string` - The queries used to search for files. + The URL of the image output from the code interpreter. - - `status: "in_progress" or "searching" or "completed" or 2 more` + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - `"in_progress"` - - `"searching"` - - `"completed"` - `"incomplete"` + - `"interpreting"` + - `"failed"` - - `type: "file_search_call"` + - `type: "code_interpreter_call"` - The type of the file search tool call. Always `file_search_call`. + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `"file_search_call"` + - `"code_interpreter_call"` - `agent: optional object { agent_name }` @@ -181155,66 +181106,63 @@ 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 }` + - `LocalShellCall object { id, action, call_id, 3 more }` - The results of the file search tool call. + A tool call to run a command on the local shell. - - `attributes: optional map[string or number or boolean]` + - `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. Keys are strings - with a maximum length of 64 characters. Values are strings with a maximum - length of 512 characters, booleans, or numbers. + The unique ID of the local shell call. - - `string` + - `action: object { command, env, type, 3 more }` - - `number` + Execute a shell command on the server. - - `boolean` + - `command: array of string` - - `file_id: optional string` + The command to run. - The unique ID of the file. + - `env: map[string]` - - `filename: optional string` + Environment variables to set for the command. - The name of the file. + - `type: "exec"` - - `score: optional number` + The type of the local shell action. Always `exec`. - The relevance score of the file - a value between 0 and 1. + - `"exec"` - - `text: optional string` + - `timeout_ms: optional number` - The text that was retrieved from the file. + Optional timeout in milliseconds for the command. - - `FunctionCall object { arguments, call_id, name, 6 more }` + - `user: optional string` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + Optional user to run the command as. - - `arguments: string` + - `working_directory: optional string` - A JSON string of the arguments to pass to the function. + Optional working directory to run the command in. - `call_id: string` - The unique ID of the function tool call generated by the model. + The unique ID of the local shell tool call generated by the model. - - `name: string` + - `status: "in_progress" or "completed" or "incomplete"` - The name of the function to run. + The status of the local shell call. - - `type: "function_call"` + - `"in_progress"` - The type of the function tool call. Always `function_call`. + - `"completed"` - - `"function_call"` + - `"incomplete"` - - `id: optional string` + - `type: "local_shell_call"` - The unique ID of the function tool call. + The type of the local shell call. Always `local_shell_call`. + + - `"local_shell_call"` - `agent: optional object { agent_name }` @@ -181224,34 +181172,35 @@ 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 }` + - `LocalShellCallOutput object { id, output, type, 2 more }` - The execution context that produced this tool call. + The output of a local shell tool call. - - `Direct object { type }` + - `id: string` - - `type: "direct"` + The unique ID of the local shell tool call generated by the model. - - `"direct"` + - `output: string` - - `Program object { caller_id, type }` + A JSON string of the output of the local shell tool call. - - `caller_id: string` + - `type: "local_shell_call_output"` - The call ID of the program item that produced this tool call. + The type of the local shell tool call output. Always `local_shell_call_output`. - - `type: "program"` + - `"local_shell_call_output"` - - `"program"` + - `agent: optional object { agent_name }` - - `namespace: optional string` + The agent that produced this item. - The namespace of the function to run. + - `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 the item. One of `in_progress`, `completed`, or `incomplete`. - `"in_progress"` @@ -181259,57 +181208,39 @@ 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. + - `ShellCall object { action, call_id, type, 5 more }` - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + A tool representing a request to execute one or more shell commands. - Text, image, or file output of the function call. + - `action: object { commands, max_output_length, timeout_ms }` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + The shell commands and limits that describe how to run the tool call. - A text input to the model. + - `commands: array of string` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + Ordered shell commands for the execution environment to run. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `max_output_length: optional number` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - A file input to the model. + - `timeout_ms: optional number` - - `status: "in_progress" or "completed" or "incomplete"` + Maximum wall-clock time in milliseconds to allow the shell commands to run. - 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 of the shell tool call generated by the model. - - `"completed"` + - `type: "shell_call"` - - `"incomplete"` + The type of the item. Always `shell_call`. - - `type: "function_call_output"` + - `"shell_call"` - The type of the function tool call output. Always `function_call_output`. + - `id: optional string` - - `"function_call_output"` + The unique ID of the shell tool call. Populated when this item is returned via API. - `agent: optional object { agent_name }` @@ -181343,189 +181274,183 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"program"` - - `created_by: optional string` - - The identifier of the actor that created the item. - - - `AgentMessage object { id, author, content, 3 more }` - - - `id: string` + - `environment: optional BetaLocalEnvironment or BetaContainerReference` - The unique ID of the agent message. + The environment to execute the shell commands in. - - `author: string` + - `BetaLocalEnvironment object { type, skills }` - The sending agent identity. + - `BetaContainerReference object { container_id, type }` - - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` + - `status: optional "in_progress" or "completed" or "incomplete"` - Encrypted content sent between agents. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `"in_progress"` - A text input to the model. + - `"completed"` - - `BetaResponseOutputText object { annotations, text, type, logprobs }` + - `"incomplete"` - A text output from the model. + - `ShellCallOutput object { call_id, output, type, 5 more }` - - `Text object { text, type }` + The streamed output items emitted by a shell tool call. - A text content. + - `call_id: string` - - `text: string` + The unique ID of the shell tool call generated by the model. - - `type: "text"` + - `output: array of BetaResponseFunctionShellCallOutputContent` - - `"text"` + Captured chunks of stdout and stderr output, along with their associated outcomes. - - `SummaryText object { text, type }` + - `outcome: object { type } or object { exit_code, type }` - A summary text from the model. + The exit or timeout outcome associated with this shell call. - - `text: string` + - `stderr: string` - A summary of the reasoning output from the model so far. + Captured stderr output for the shell call. - - `type: "summary_text"` + - `stdout: string` - The type of the object. Always `summary_text`. + Captured stdout output for the shell call. - - `"summary_text"` + - `type: "shell_call_output"` - - `ReasoningText object { text, type }` + The type of the item. Always `shell_call_output`. - Reasoning text from the model. + - `"shell_call_output"` - - `text: string` + - `id: optional string` - The reasoning text from the model. + The unique ID of the shell tool call output. Populated when this item is returned via API. - - `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` - - `BetaResponseOutputRefusal object { refusal, type }` + The canonical name of the agent that produced this item. - A refusal from the model. + - `caller: optional object { type } or object { caller_id, type }` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + The execution context that produced this tool call. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `Direct object { type }` - - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` + - `type: "direct"` - A screenshot of a computer. + The caller type. Always `direct`. - - `detail: "low" or "high" or "auto" or "original"` + - `"direct"` - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `Program object { caller_id, type }` - - `"low"` + - `caller_id: string` - - `"high"` + The call ID of the program item that produced this tool call. - - `"auto"` + - `type: "program"` - - `"original"` + The caller type. Always `program`. - - `file_id: string` + - `"program"` - The identifier of an uploaded file that contains the screenshot. + - `max_output_length: optional number` - - `image_url: string` + The maximum number of UTF-8 characters captured for this shell call's combined output. - The URL of the screenshot image. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `type: "computer_screenshot"` + The status of the shell call output. - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + - `"in_progress"` - - `"computer_screenshot"` + - `"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. - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - A file input to the model. + The specific create, delete, or update instruction for the apply_patch tool call. - - `EncryptedContent object { encrypted_content, type }` + - `CreateFile object { diff, path, type }` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + Instruction for creating a new file via the apply_patch tool. - - `encrypted_content: string` + - `diff: string` - Opaque encrypted content. + Unified diff content to apply when creating the file. - - `type: "encrypted_content"` + - `path: string` - The type of the input item. Always `encrypted_content`. + Path of the file to create relative to the workspace root. - - `"encrypted_content"` + - `type: "create_file"` - - `recipient: string` + The operation type. Always `create_file`. - The destination agent identity. + - `"create_file"` - - `type: "agent_message"` + - `DeleteFile object { path, type }` - The type of the item. Always `agent_message`. + Instruction for deleting an existing file via the apply_patch tool. - - `"agent_message"` + - `path: string` - - `agent: optional object { agent_name }` + Path of the file to delete relative to the workspace root. - The agent that produced this item. + - `type: "delete_file"` - - `agent_name: string` + The operation type. Always `delete_file`. - The canonical name of the agent that produced this item. + - `"delete_file"` - - `MultiAgentCall object { id, action, arguments, 3 more }` + - `UpdateFile object { diff, path, type }` - - `id: string` + Instruction for updating an existing file via the apply_patch tool. - The unique ID of the multi-agent call item. + - `diff: string` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + Unified diff content to apply to the existing file. - The multi-agent action to execute. + - `path: string` - - `"spawn_agent"` + Path of the file to update relative to the workspace root. - - `"interrupt_agent"` + - `type: "update_file"` - - `"list_agents"` + The operation type. Always `update_file`. - - `"send_message"` + - `"update_file"` - - `"followup_task"` + - `status: "in_progress" or "completed"` - - `"wait_agent"` + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `arguments: string` + - `"in_progress"` - The JSON string of arguments generated for the action. + - `"completed"` - - `call_id: string` + - `type: "apply_patch_call"` - The unique ID linking this call to its output. + The type of the item. Always `apply_patch_call`. - - `type: "multi_agent_call"` + - `"apply_patch_call"` - The type of the multi-agent call. Always `multi_agent_call`. + - `id: optional string` - - `"multi_agent_call"` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - `agent: optional object { agent_name }` @@ -181535,55 +181460,55 @@ 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 }` + - `caller: optional object { type } or object { caller_id, type }` - - `id: string` + The execution context that produced this tool call. - The unique ID of the multi-agent call output item. + - `Direct object { type }` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `type: "direct"` - The multi-agent action that produced this result. + The caller type. Always `direct`. - - `"spawn_agent"` + - `"direct"` - - `"interrupt_agent"` + - `Program object { caller_id, type }` - - `"list_agents"` + - `caller_id: string` - - `"send_message"` + The call ID of the program item that produced this tool call. - - `"followup_task"` + - `type: "program"` - - `"wait_agent"` + The caller type. Always `program`. - - `call_id: string` + - `"program"` - The unique ID of the multi-agent call. + - `ApplyPatchCallOutput object { call_id, status, type, 4 more }` - - `output: array of BetaResponseOutputText` + The streamed output emitted by an apply patch tool call. - 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 apply patch tool call generated by the model. - The annotations of the text output. + - `status: "completed" or "failed"` - - `text: string` + The status of the apply patch tool call output. One of `completed` or `failed`. - The text output from the model. + - `"completed"` - - `type: "output_text"` + - `"failed"` - The type of the output text. Always `output_text`. + - `type: "apply_patch_call_output"` - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + The type of the item. Always `apply_patch_call_output`. - - `type: "multi_agent_call_output"` + - `"apply_patch_call_output"` - The type of the multi-agent result. Always `multi_agent_call_output`. + - `id: optional string` - - `"multi_agent_call_output"` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - `agent: optional object { agent_name }` @@ -181593,101 +181518,71 @@ curl -X POST https://api.openai.com/v1/responses/compact \ 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](https://platform.openai.com/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. + - `caller: optional object { type } or object { caller_id, type }` - - `sources: optional array of object { type, url }` + The execution context that produced this tool call. - The sources used in the search. + - `Direct object { type }` - - `type: "url"` + - `type: "direct"` - The type of source. Always `url`. + The caller type. Always `direct`. - - `"url"` + - `"direct"` - - `url: string` + - `Program object { caller_id, type }` - The URL of the source. + - `caller_id: string` - - `OpenPage object { type, url }` + The call ID of the program item that produced this tool call. - Action type "open_page" - Opens a specific URL from search results. + - `type: "program"` - - `type: "open_page"` + The caller type. Always `program`. - The action type. + - `"program"` - - `"open_page"` + - `output: optional string` - - `url: optional string` + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - The URL opened by the model. + - `McpListTools object { id, server_label, tools, 3 more }` - - `FindInPage object { pattern, type, url }` + A list of tools available on an MCP server. - Action type "find_in_page": Searches for a pattern within a loaded page. + - `id: string` - - `pattern: string` + The unique ID of the list. - The pattern or text to search for within the page. + - `server_label: string` - - `type: "find_in_page"` + The label of the MCP server. - The action type. + - `tools: array of object { input_schema, name, annotations, description }` - - `"find_in_page"` + The tools available on the server. - - `url: string` + - `input_schema: unknown` - The URL of the page searched for the pattern. + The JSON schema describing the tool's input. - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `name: string` - The status of the web search tool call. + The name of the tool. - - `"in_progress"` + - `annotations: optional unknown` - - `"searching"` + Additional annotations about the tool. - - `"completed"` + - `description: optional string` - - `"failed"` + The description of the tool. - - `type: "web_search_call"` + - `type: "mcp_list_tools"` - The type of the web search tool call. Always `web_search_call`. + The type of the item. Always `mcp_list_tools`. - - `"web_search_call"` + - `"mcp_list_tools"` - `agent: optional object { agent_name }` @@ -181697,60 +181592,35 @@ 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 }` - - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - - - `id: string` - - The unique ID of the computer call. - - - `call_id: string` + - `error: optional string` - An identifier used when responding to the tool call with output. + Error message if the server could not list tools. - - `pending_safety_checks: array of object { id, code, message }` + - `McpApprovalRequest object { id, arguments, name, 3 more }` - The pending safety checks for the computer call. + A request for human approval of a tool invocation. - `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"` + The unique ID of the approval request. - - `"completed"` + - `arguments: string` - - `"incomplete"` + A JSON string of arguments for the tool. - - `type: "computer_call"` + - `name: string` - The type of the computer call. Always `computer_call`. + The name of the tool to run. - - `"computer_call"` + - `server_label: string` - - `action: optional BetaComputerAction` + The label of the MCP server making the request. - A click action. + - `type: "mcp_approval_request"` - - `actions: optional BetaComputerActionList` + The type of the item. Always `mcp_approval_request`. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `"mcp_approval_request"` - `agent: optional object { agent_name }` @@ -181760,55 +181630,27 @@ curl -X POST https://api.openai.com/v1/responses/compact \ 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"` - - - `"in_progress"` - - - `type: "computer_call_output"` + - `McpApprovalResponse object { approval_request_id, approve, type, 3 more }` - The type of the computer tool call output. Always `computer_call_output`. + A response to an MCP approval request. - - `"computer_call_output"` + - `approval_request_id: string` - - `acknowledged_safety_checks: optional array of object { id, code, message }` + The ID of the approval request being answered. - The safety checks reported by the API that have been acknowledged by the - developer. + - `approve: boolean` - - `id: string` + Whether the request was approved. - The ID of the pending safety check. + - `type: "mcp_approval_response"` - - `code: optional string` + The type of the item. Always `mcp_approval_response`. - The type of the pending safety check. + - `"mcp_approval_response"` - - `message: optional string` + - `id: optional string` - Details about the pending safety check. + The unique ID of the approval response - `agent: optional object { agent_name }` @@ -181818,40 +181660,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` + - `reason: optional string` - The identifier of the actor that created the item. + Optional reason for the decision. - - `Reasoning object { id, summary, type, 4 more }` + - `McpCall object { id, arguments, name, 7 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](https://platform.openai.com/docs/guides/conversation-state). + An invocation of a tool on an MCP server. - `id: string` - The unique identifier of the reasoning content. - - - `summary: array of object { text, type }` + The unique ID of the tool call. - Reasoning summary content. + - `arguments: string` - - `text: string` + A JSON string of the arguments passed to the tool. - A summary of the reasoning output from the model so far. + - `name: string` - - `type: "summary_text"` + The name of the tool that was run. - The type of the object. Always `summary_text`. + - `server_label: string` - - `"summary_text"` + The label of the MCP server running the tool. - - `type: "reasoning"` + - `type: "mcp_call"` - The type of the object. Always `reasoning`. + The type of the item. Always `mcp_call`. - - `"reasoning"` + - `"mcp_call"` - `agent: optional object { agent_name }` @@ -181861,29 +181698,22 @@ 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. + - `approval_request_id: optional string` - - `type: "reasoning_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. - The type of the reasoning text. Always `reasoning_text`. + - `error: optional string` - - `"reasoning_text"` + The error from the tool call, if any. - - `encrypted_content: optional string` + - `output: optional string` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + The output from the tool call. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - `"in_progress"` @@ -181891,65 +181721,52 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"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` + - `"calling"` - Opaque program replay fingerprint that must be round-tripped. + - `"failed"` - - `type: "program"` + - `CustomToolCallOutput object { call_id, output, type, 3 more }` - The type of the item. Always `program`. + The output of a custom tool call from your code, being sent back to the model. - - `"program"` + - `call_id: string` - - `agent: optional object { agent_name }` + The call ID, used to map this custom tool call output to a custom tool call. - The agent that produced this item. + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `agent_name: string` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - The canonical name of the agent that produced this item. + - `StringOutput = string` - - `ProgramOutput object { id, call_id, result, 3 more }` + A string of the output of the custom tool call. - - `id: string` + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - The unique ID of the program output item. + Text, image, or file output of the custom tool call. - - `call_id: string` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - The call ID of the program item. + A text input to the model. - - `result: string` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - The result produced by the program item. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `status: "completed" or "incomplete"` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - The terminal status of the program output item. + A file input to the model. - - `"completed"` + - `type: "custom_tool_call_output"` - - `"incomplete"` + The type of the custom tool call output. Always `custom_tool_call_output`. - - `type: "program_output"` + - `"custom_tool_call_output"` - The type of the item. Always `program_output`. + - `id: optional string` - - `"program_output"` + The unique ID of the custom tool call output in the OpenAI platform. - `agent: optional object { agent_name }` @@ -181959,2139 +181776,2062 @@ 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` - - 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"` + - `caller: optional object { type } or object { caller_id, type }` - - `"client"` + The execution context that produced this tool call. - - `status: "in_progress" or "completed" or "incomplete"` + - `Direct object { type }` - The status of the tool search call item that was recorded. + - `type: "direct"` - - `"in_progress"` + The caller type. Always `direct`. - - `"completed"` + - `"direct"` - - `"incomplete"` + - `Program object { caller_id, type }` - - `type: "tool_search_call"` + - `caller_id: string` - The type of the item. Always `tool_search_call`. + The call ID of the program item that produced this tool call. - - `"tool_search_call"` + - `type: "program"` - - `agent: optional object { agent_name }` + The caller type. Always `program`. - The agent that produced this item. + - `"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. - - `created_by: optional string` + - `call_id: string` - The identifier of the actor that created the item. + An identifier used to map this custom tool call to a tool call output. - - `ToolSearchOutput object { id, call_id, execution, 5 more }` + - `input: string` - - `id: string` + The input for the custom tool call generated by the model. - The unique ID of the tool search output item. + - `name: string` - - `call_id: string` + The name of the custom tool being called. - The unique ID of the tool search call generated by the model. + - `type: "custom_tool_call"` - - `execution: "server" or "client"` + The type of the custom tool call. Always `custom_tool_call`. - Whether tool search was executed by the server or by the client. + - `"custom_tool_call"` - - `"server"` + - `id: optional string` - - `"client"` + The unique ID of the custom tool call in the OpenAI platform. - - `status: "in_progress" or "completed" or "incomplete"` + - `agent: optional object { agent_name }` - The status of the tool search output item that was recorded. + 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 }` - - `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 execution context that produced this tool call. - The loaded tool definitions returned by tool search. + - `Direct object { type }` - - `Function object { name, parameters, strict, 5 more }` + - `type: "direct"` - 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). + - `"direct"` - - `name: string` + - `Program object { caller_id, type }` - The name of the function to call. + - `caller_id: string` - - `parameters: map[unknown]` + The call ID of the program item that produced this tool call. - A JSON schema object describing the parameters of the function. + - `type: "program"` - - `strict: boolean` + - `"program"` - Whether strict parameter validation is enforced for this function tool. + - `namespace: optional string` - - `type: "function"` + The namespace of the custom tool being called. - The type of the function tool. Always `function`. + - `CompactionTrigger object { type, agent }` - - `"function"` + Compacts the current context. Must be the final input item. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `type: "compaction_trigger"` - The tool invocation context(s). + The type of the item. Always `compaction_trigger`. - - `"direct"` + - `"compaction_trigger"` - - `"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. + - `ItemReference object { id, agent, type }` - - `output_schema: optional map[unknown]` + An internal identifier for an item to reference. - 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 ID of the item to reference. - 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: optional object { agent_name }` - - `type: "file_search"` + The agent that produced this item. - The type of the file search tool. Always `file_search`. + - `agent_name: string` - - `"file_search"` + The canonical name of the agent that produced this item. - - `vector_store_ids: array of string` + - `type: optional "item_reference"` - The IDs of the vector stores to search. + The type of item to reference. Always `item_reference`. - - `filters: optional object { key, type, value } or object { filters, type }` + - `"item_reference"` - A filter to apply. + - `Program object { id, call_id, code, 3 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. + The unique ID of this program item. - - `key: string` + - `call_id: string` - The key to compare against the value. + The stable call ID of the program item. - - `type: "eq" or "ne" or "gt" or 5 more` + - `code: string` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The JavaScript source executed by programmatic tool calling. - - `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 + - `fingerprint: string` - - `"eq"` + Opaque program replay fingerprint that must be round-tripped. - - `"ne"` + - `type: "program"` - - `"gt"` + The item type. Always `program`. - - `"gte"` + - `"program"` - - `"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` + - `ProgramOutput object { id, call_id, result, 3 more }` - The value to compare against the attribute key; supports string, number, or boolean types. + - `id: string` - - `string` + The unique ID of this program output item. - - `number` + - `call_id: string` - - `boolean` + The call ID of the program item. - - `array of string or number` + - `result: string` - - `string` + The result produced by the program item. - - `number` + - `status: "completed" or "incomplete"` - - `CompoundFilter object { filters, type }` + The terminal status of the program output. - 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`. + - `type: "program_output"` - - `ComparisonFilter object { key, type, value }` + The item type. Always `program_output`. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `"program_output"` - - `key: string` + - `agent: optional object { agent_name }` - The key to compare against the value. + The agent that produced this item. - - `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 + - `response_id: string` - - `"eq"` + The ID of the active response that should receive the input. - - `"ne"` + - `type: "response.inject"` - - `"gt"` + The event discriminator. Always `response.inject`. - - `"gte"` + - `"response.inject"` - - `"lt"` +### Beta Responses Server Event - - `"lte"` +- `BetaResponsesServerEvent = BetaResponseAudioDeltaEvent or BetaResponseAudioDoneEvent or BetaResponseAudioTranscriptDeltaEvent or 52 more` - - `"in"` + Server events emitted by the Responses WebSocket server. - - `"nin"` + - `BetaResponseAudioDeltaEvent object { delta, sequence_number, type, agent }` - - `value: string or number or boolean or array of string or number` + Emitted when there is a partial audio response. - The value to compare against the attribute key; supports string, number, or boolean types. + - `delta: string` - - `string` + A chunk of Base64 encoded response audio bytes. - - `number` + - `sequence_number: number` - - `boolean` + A sequence number for this chunk of the stream response. - - `array of string or number` + - `type: "response.audio.delta"` - - `string` + The type of the event. Always `response.audio.delta`. - - `number` + - `"response.audio.delta"` - - `unknown` + - `agent: optional object { agent_name }` - - `type: "and" or "or"` + The agent that owns this multi-agent streaming event. - Type of operation: `and` or `or`. + - `agent_name: string` - - `"and"` + The canonical name of the agent that produced this item. - - `"or"` + - `BetaResponseAudioDoneEvent object { sequence_number, type, agent }` - - `max_num_results: optional number` + Emitted when the audio response is complete. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `sequence_number: number` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + The sequence number of the delta. - Ranking options for search. + - `type: "response.audio.done"` - - `hybrid_search: optional object { embedding_weight, text_weight }` + The type of the event. Always `response.audio.done`. - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `"response.audio.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"` + - `BetaResponseAudioTranscriptDeltaEvent object { delta, sequence_number, type, agent }` - The ranker to use for the file search. + Emitted when there is a partial transcript of audio. - - `"auto"` + - `delta: string` - - `"default-2024-11-15"` + The partial transcript of the audio response. - - `score_threshold: optional number` + - `sequence_number: number` - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + The sequence number of this event. - - `Computer object { type }` + - `type: "response.audio.transcript.delta"` - 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 event. Always `response.audio.transcript.delta`. - - `type: "computer"` + - `"response.audio.transcript.delta"` - The type of the computer tool. Always `computer`. + - `agent: optional object { agent_name }` - - `"computer"` + The agent that owns this multi-agent streaming event. - - `ComputerUsePreview object { display_height, display_width, environment, type }` + - `agent_name: string` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The canonical name of the agent that produced this item. - - `display_height: number` + - `BetaResponseAudioTranscriptDoneEvent object { sequence_number, type, agent }` - The height of the computer display. + Emitted when the full audio transcript is completed. - - `display_width: number` + - `sequence_number: number` - The width of the computer display. + The sequence number of this event. - - `environment: "windows" or "mac" or "linux" or 2 more` + - `type: "response.audio.transcript.done"` - The type of computer environment to control. + The type of the event. Always `response.audio.transcript.done`. - - `"windows"` + - `"response.audio.transcript.done"` - - `"mac"` + - `agent: optional object { agent_name }` - - `"linux"` + The agent that owns this multi-agent streaming event. - - `"ubuntu"` + - `agent_name: string` - - `"browser"` + The canonical name of the agent that produced this item. - - `type: "computer_use_preview"` + - `BetaResponseCodeInterpreterCallCodeDeltaEvent object { delta, item_id, output_index, 3 more }` - The type of the computer use tool. Always `computer_use_preview`. + Emitted when a partial code snippet is streamed by the code interpreter. - - `"computer_use_preview"` + - `delta: string` - - `WebSearch object { type, filters, search_context_size, user_location }` + The partial code snippet being streamed by the code interpreter. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `item_id: string` - - `type: "web_search" or "web_search_2025_08_26"` + The unique identifier of the code interpreter tool call item. - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `output_index: number` - - `"web_search"` + The index of the output item in the response for which the code is being streamed. - - `"web_search_2025_08_26"` + - `sequence_number: number` - - `filters: optional object { allowed_domains }` + The sequence number of this event, used to order streaming events. - Filters for the search. + - `type: "response.code_interpreter_call_code.delta"` - - `allowed_domains: optional array of string` + The type of the event. Always `response.code_interpreter_call_code.delta`. - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `"response.code_interpreter_call_code.delta"` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `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"` + - `BetaResponseCodeInterpreterCallCodeDoneEvent object { code, item_id, output_index, 3 more }` - - `"high"` + Emitted when the code snippet is finalized by the code interpreter. - - `user_location: optional object { city, country, region, 2 more }` + - `code: string` - The approximate location of the user. + The final code snippet output by the code interpreter. - - `city: optional string` + - `item_id: string` - Free text input for the city of the user, e.g. `San Francisco`. + The unique identifier of the code interpreter tool call item. - - `country: optional string` + - `output_index: number` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The index of the output item in the response for which the code is finalized. - - `region: optional string` + - `sequence_number: number` - Free text input for the region of the user, e.g. `California`. + The sequence number of this event, used to order streaming events. - - `timezone: optional string` + - `type: "response.code_interpreter_call_code.done"` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The type of the event. Always `response.code_interpreter_call_code.done`. - - `type: optional "approximate"` + - `"response.code_interpreter_call_code.done"` - The type of location approximation. Always `approximate`. + - `agent: optional object { agent_name }` - - `"approximate"` + The agent that owns this multi-agent streaming event. - - `Mcp object { server_label, type, allowed_callers, 9 more }` + - `agent_name: string` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + The canonical name of the agent that produced this item. - - `server_label: string` + - `BetaResponseCodeInterpreterCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` - A label for this MCP server, used to identify it in tool calls. + Emitted when the code interpreter call is completed. - - `type: "mcp"` + - `item_id: string` - The type of the MCP tool. Always `mcp`. + The unique identifier of the code interpreter tool call item. - - `"mcp"` + - `output_index: number` - - `allowed_callers: optional array of "direct" or "programmatic"` + The index of the output item in the response for which the code interpreter call is completed. - The tool invocation context(s). + - `sequence_number: number` - - `"direct"` + The sequence number of this event, used to order streaming events. - - `"programmatic"` + - `type: "response.code_interpreter_call.completed"` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + The type of the event. Always `response.code_interpreter_call.completed`. - List of allowed tool names or a filter object. + - `"response.code_interpreter_call.completed"` - - `McpAllowedTools = array of string` + - `agent: optional object { agent_name }` - A string array of allowed tool names + The agent that owns this multi-agent streaming event. - - `McpToolFilter 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` + - `BetaResponseCodeInterpreterCallInProgressEvent object { item_id, output_index, sequence_number, 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. + Emitted when a code interpreter call is in progress. - - `tool_names: optional array of string` + - `item_id: string` - List of allowed tool names. + The unique identifier of the code interpreter tool call item. - - `authorization: optional string` + - `output_index: 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. + The index of the output item in the response for which the code interpreter call is in progress. - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + - `sequence_number: 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + The sequence number of this event, used to order streaming events. - Currently supported `connector_id` values are: + - `type: "response.code_interpreter_call.in_progress"` - - 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 event. Always `response.code_interpreter_call.in_progress`. - - `"connector_dropbox"` + - `"response.code_interpreter_call.in_progress"` - - `"connector_gmail"` + - `agent: optional object { agent_name }` - - `"connector_googlecalendar"` + The agent that owns this multi-agent streaming event. - - `"connector_googledrive"` + - `agent_name: string` - - `"connector_microsoftteams"` + The canonical name of the agent that produced this item. - - `"connector_outlookcalendar"` + - `BetaResponseCodeInterpreterCallInterpretingEvent object { item_id, output_index, sequence_number, 2 more }` - - `"connector_outlookemail"` + Emitted when the code interpreter is actively interpreting the code snippet. - - `"connector_sharepoint"` + - `item_id: string` - - `defer_loading: optional boolean` + The unique identifier of the code interpreter tool call item. - Whether this MCP tool is deferred and discovered via tool search. + - `output_index: number` - - `headers: optional map[string]` + The index of the output item in the response for which the code interpreter is interpreting code. - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `sequence_number: number` - - `require_approval: optional object { always, never } or "always" or "never"` + The sequence number of this event, used to order streaming events. - Specify which of the MCP server's tools require approval. + - `type: "response.code_interpreter_call.interpreting"` - - `McpToolApprovalFilter object { always, never }` + The type of the event. Always `response.code_interpreter_call.interpreting`. - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `"response.code_interpreter_call.interpreting"` - - `always: optional object { read_only, tool_names }` + - `agent: optional object { agent_name }` - A filter object to specify which tools are allowed. + The agent that owns this multi-agent streaming event. - - `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` + - `BetaResponseCompletedEvent object { response, sequence_number, type, agent }` - List of allowed tool names. + Emitted when the model response is complete. - - `never: optional object { read_only, tool_names }` + - `response: BetaResponse` - A filter object to specify which tools are allowed. + Properties of the completed response. - - `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. + Unique identifier for this Response. - - `tool_names: optional array of string` + - `created_at: number` - List of allowed tool names. + Unix timestamp (in seconds) of when this Response was created. - - `McpToolApprovalSetting = "always" or "never"` + - `error: BetaResponseError` - 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. + An error object returned when the model fails to generate a Response. - - `"always"` + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 16 more` - - `"never"` + The error code for the response. - - `server_description: optional string` + - `"server_error"` - Optional description of the MCP server, used to provide more context. + - `"rate_limit_exceeded"` - - `server_url: optional string` + - `"invalid_prompt"` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `"bio_policy"` - - `tunnel_id: optional string` + - `"vector_store_timeout"` - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. + - `"invalid_image"` - - `CodeInterpreter object { container, type, allowed_callers }` + - `"invalid_image_format"` - A tool that runs Python code to help generate a response to a prompt. + - `"invalid_base64_image"` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + - `"invalid_image_url"` - 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. + - `"image_too_large"` - - `string` + - `"image_too_small"` - The container ID. + - `"image_parse_error"` - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + - `"image_content_policy_violation"` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `"invalid_image_mode"` - - `type: "auto"` + - `"image_file_too_large"` - Always `auto`. + - `"unsupported_image_media_type"` - - `"auto"` + - `"empty_image_file"` - - `file_ids: optional array of string` + - `"failed_to_download_image"` - An optional list of uploaded files to make available to your code. + - `"image_file_not_found"` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `message: string` - The memory limit for the code interpreter container. + A human-readable description of the error. - - `"1g"` + - `incomplete_details: object { reason }` - - `"4g"` + Details about why the response is incomplete. - - `"16g"` + - `reason: optional "max_output_tokens" or "content_filter"` - - `"64g"` + The reason why the response is incomplete. - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `"max_output_tokens"` - Network access policy for the container. + - `"content_filter"` - - `BetaContainerNetworkPolicyDisabled object { type }` + - `instructions: string or array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` - - `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`. + - `string` - - `"code_interpreter"` + A text input to the model, equivalent to a text input with the + `developer` role. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `InputItemList = array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` - The tool invocation context(s). + A list of one or many input items to the model, containing + different content types. - - `"direct"` + - `BetaEasyInputMessage object { content, role, phase, type }` - - `"programmatic"` + 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. - - `ProgrammaticToolCalling object { type }` + - `content: string or BetaResponseInputMessageContentList` - - `type: "programmatic_tool_calling"` + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - The type of the tool. Always `programmatic_tool_calling`. + - `TextInput = string` - - `"programmatic_tool_calling"` + A text input to the model. - - `ImageGeneration object { type, action, background, 9 more }` + - `BetaResponseInputMessageContentList = array of BetaResponseInputContent` - A tool that generates images using the GPT image models. + A list of one or many input items to the model, containing different content + types. - - `type: "image_generation"` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - The type of the image generation tool. Always `image_generation`. + A text input to the model. - - `"image_generation"` + - `text: string` - - `action: optional "generate" or "edit" or "auto"` + The text input to the model. - Whether to generate a new image or edit an existing image. Default: `auto`. + - `type: "input_text"` - - `"generate"` + The type of the input item. Always `input_text`. - - `"edit"` + - `"input_text"` - - `"auto"` + - `prompt_cache_breakpoint: optional object { mode }` - - `background: optional "transparent" or "opaque" or "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. - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + - `mode: "explicit"` - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + The breakpoint mode. Always `explicit`. - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `"explicit"` - - `"transparent"` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `"opaque"` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `"auto"` + - `detail: "low" or "high" or "auto" or "original"` - - `input_fidelity: optional "high" or "low"` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - 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`. + - `"low"` - `"high"` - - `"low"` + - `"auto"` - - `input_image_mask: optional object { file_id, image_url }` + - `"original"` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `type: "input_image"` + + The type of the input item. Always `input_image`. + + - `"input_image"` - `file_id: optional string` - File ID for the mask image. + The ID of the file to be sent to the model. - `image_url: optional string` - Base64-encoded mask image. - - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - The image generation model to use. Default: `gpt-image-1`. + - `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. - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `mode: "explicit"` - The image generation model to use. Default: `gpt-image-1`. + The breakpoint mode. Always `explicit`. - - `"gpt-image-1"` + - `"explicit"` - - `"gpt-image-1-mini"` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `"gpt-image-2"` + A file input to the model. - - `"gpt-image-2-2026-04-21"` + - `type: "input_file"` - - `"gpt-image-1.5"` + The type of the input item. Always `input_file`. - - `"chatgpt-image-latest"` + - `"input_file"` - - `moderation: optional "auto" or "low"` + - `detail: optional "auto" or "low" or "high"` - Moderation level for the generated image. Default: `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`. - `"auto"` - `"low"` - - `output_compression: optional number` + - `"high"` - Compression level for the output image. Default: 100. + - `file_data: optional string` - - `output_format: optional "png" or "webp" or "jpeg"` + The content of the file to be sent to the model. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `file_id: optional string` - - `"png"` + The ID of the file to be sent to the model. - - `"webp"` + - `file_url: optional string` - - `"jpeg"` + The URL of the file to be sent to the model. - - `partial_images: optional number` + - `filename: optional string` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + The name of the file to be sent to the model. - - `quality: optional "low" or "medium" or "high" or "auto"` + - `prompt_cache_breakpoint: optional object { mode }` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `"low"` + - `mode: "explicit"` - - `"medium"` + The breakpoint mode. Always `explicit`. - - `"high"` + - `"explicit"` - - `"auto"` + - `role: "user" or "assistant" or "system" or "developer"` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `"user"` - - `string` + - `"assistant"` - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `"system"` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `"developer"` - - `"1024x1024"` + - `phase: optional "commentary" or "final_answer"` - - `"1024x1536"` + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - `"1536x1024"` + - `"commentary"` - - `"auto"` + - `"final_answer"` - - `LocalShell object { type }` + - `type: optional "message"` - A tool that allows the model to execute shell commands in a local environment. + The type of the message input. Always `message`. - - `type: "local_shell"` + - `"message"` - The type of the local shell tool. Always `local_shell`. + - `Message object { content, role, agent, 2 more }` - - `"local_shell"` + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. - - `Shell object { type, allowed_callers, environment }` + - `content: BetaResponseInputMessageContentList` - A tool that allows the model to execute shell commands. + A list of one or many input items to the model, containing different content + types. - - `type: "shell"` + - `role: "user" or "system" or "developer"` - The type of the shell tool. Always `shell`. + The role of the message input. One of `user`, `system`, or `developer`. - - `"shell"` + - `"user"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"system"` - The tool invocation context(s). + - `"developer"` - - `"direct"` + - `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 }` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `BetaContainerReference object { container_id, type }` + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `Custom object { name, type, allowed_callers, 3 more }` + - `"in_progress"` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `"completed"` - - `name: string` + - `"incomplete"` - The name of the custom tool, used to identify it in tool calls. + - `type: optional "message"` - - `type: "custom"` + The type of the message input. Always set to `message`. - The type of the custom tool. Always `custom`. + - `"message"` - - `"custom"` + - `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). + - `id: string` - - `"direct"` + The unique ID of the output message. - - `"programmatic"` + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - - `defer_loading: optional boolean` + The content of the output message. - Whether this tool should be deferred and discovered via tool search. + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - - `description: optional string` + A text output from the model. - Optional description of the custom tool, used to provide more 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 }` - - `format: optional object { type } or object { definition, syntax, type }` + The annotations of the text output. - The input format for the custom tool. Default is unconstrained text. + - `FileCitation object { file_id, filename, index, type }` - - `Text object { type }` + A citation to a file. - Unconstrained free-form text. + - `file_id: string` - - `type: "text"` + The ID of the file. - Unconstrained text format. Always `text`. + - `filename: string` - - `"text"` + The filename of the file cited. - - `Grammar object { definition, syntax, type }` + - `index: number` - A grammar defined by the user. + The index of the file in the list of files. - - `definition: string` + - `type: "file_citation"` - The grammar definition. + The type of the file citation. Always `file_citation`. - - `syntax: "lark" or "regex"` + - `"file_citation"` - The syntax of the grammar definition. One of `lark` or `regex`. + - `URLCitation object { end_index, start_index, title, 2 more }` - - `"lark"` + A citation for a web resource used to generate a model response. - - `"regex"` + - `end_index: number` - - `type: "grammar"` + The index of the last character of the URL citation in the message. - Grammar format. Always `grammar`. + - `start_index: number` - - `"grammar"` + The index of the first character of the URL citation in the message. - - `Namespace object { description, name, tools, type }` + - `title: string` - Groups function/custom tools under a shared namespace. + The title of the web resource. - - `description: string` + - `type: "url_citation"` - A description of the namespace shown to the model. + The type of the URL citation. Always `url_citation`. - - `name: string` + - `"url_citation"` - The namespace name used in tool calls (for example, `crm`). + - `url: string` - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + The URL of the web resource. - The function/custom tools available inside this namespace. + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - - `Function object { name, type, allowed_callers, 5 more }` + A citation for a container file used to generate a model response. - - `name: string` + - `container_id: string` - - `type: "function"` + The ID of the container file. - - `"function"` + - `end_index: number` - - `allowed_callers: optional array of "direct" or "programmatic"` + The index of the last character of the container file citation in the message. - The tool invocation context(s). + - `file_id: string` - - `"direct"` + The ID of the file. - - `"programmatic"` + - `filename: string` - - `defer_loading: optional boolean` + The filename of the container file cited. - Whether this function should be deferred and discovered via tool search. + - `start_index: number` - - `description: optional string` + The index of the first character of the container file citation in the message. - - `output_schema: optional map[unknown]` + - `type: "container_file_citation"` - 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 container file citation. Always `container_file_citation`. - - `parameters: optional unknown` + - `"container_file_citation"` - - `strict: optional boolean` + - `FilePath object { file_id, index, 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. + A path to a file. - - `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](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The ID of the file. - - `name: string` + - `index: number` - The name of the custom tool, used to identify it in tool calls. + The index of the file in the list of files. - - `type: "custom"` + - `type: "file_path"` - The type of the custom tool. Always `custom`. + The type of the file path. Always `file_path`. - - `"custom"` + - `"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` - - `defer_loading: optional boolean` + - `top_logprobs: array of object { token, bytes, logprob }` - Whether this tool should be deferred and discovered via tool search. + - `token: string` - - `description: optional string` + - `bytes: array of number` - Optional description of the custom tool, used to provide more context. + - `logprob: number` - - `format: optional object { type } or object { definition, syntax, type }` + - `text: string` - The input format for the custom tool. Default is unconstrained text. + The text output from the model. - - `Text object { type }` + - `type: "output_text"` - Unconstrained free-form text. + The type of the output text. Always `output_text`. - - `type: "text"` + - `"output_text"` - Unconstrained text format. Always `text`. + - `BetaResponseOutputRefusal object { refusal, type }` - - `"text"` + A refusal from the model. - - `Grammar object { definition, syntax, type }` + - `refusal: string` - A grammar defined by the user. + The refusal explanation from the model. - - `definition: string` + - `type: "refusal"` - The grammar definition. + The type of the refusal. Always `refusal`. - - `syntax: "lark" or "regex"` + - `"refusal"` - The syntax of the grammar definition. One of `lark` or `regex`. + - `role: "assistant"` - - `"lark"` + The role of the output message. Always `assistant`. - - `"regex"` + - `"assistant"` - - `type: "grammar"` + - `status: "in_progress" or "completed" or "incomplete"` - Grammar format. Always `grammar`. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `"grammar"` + - `"in_progress"` - - `type: "namespace"` + - `"completed"` - The type of the tool. Always `namespace`. + - `"incomplete"` - - `"namespace"` + - `type: "message"` - - `ToolSearch object { type, description, execution, parameters }` + The type of the output message. Always `message`. - Hosted or BYOT tool search configuration for deferred tools. + - `"message"` - - `type: "tool_search"` + - `agent: optional object { agent_name }` - The type of the tool. Always `tool_search`. + The agent that produced this item. - - `"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. + - `phase: optional "commentary" or "final_answer"` - - `execution: optional "server" or "client"` + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - Whether tool search is executed by the server or by the client. + - `"commentary"` - - `"server"` + - `"final_answer"` - - `"client"` + - `FileSearchCall object { id, queries, status, 3 more }` - - `parameters: optional unknown` + The results of a file search tool call. See the + [file search guide](/docs/guides/tools-file-search) for more information. - 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 file search 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). + - `queries: array of string` - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + The queries used to search for files. - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `status: "in_progress" or "searching" or "completed" or 2 more` - - `"web_search_preview"` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `"web_search_preview_2025_03_11"` + - `"in_progress"` - - `search_content_types: optional array of "text" or "image"` + - `"searching"` - - `"text"` + - `"completed"` - - `"image"` + - `"incomplete"` - - `search_context_size: optional "low" or "medium" or "high"` + - `"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. + - `type: "file_search_call"` - - `"low"` + The type of the file search tool call. Always `file_search_call`. - - `"medium"` + - `"file_search_call"` - - `"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`. + - `results: optional array of object { attributes, file_id, filename, 2 more }` - - `"approximate"` + The results of the file search tool call. - - `city: optional string` + - `attributes: optional map[string or number or boolean]` - Free text input for the city of the user, e.g. `San Francisco`. + 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. - - `country: optional string` + - `string` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `number` - - `region: optional string` + - `boolean` - Free text input for the region of the user, e.g. `California`. + - `file_id: optional string` - - `timezone: optional string` + The unique ID of the file. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `filename: optional string` - - `ApplyPatch object { type, allowed_callers }` + The name of the file. - Allows the assistant to create, delete, or update files using unified diffs. + - `score: optional number` - - `type: "apply_patch"` + The relevance score of the file - a value between 0 and 1. - The type of the tool. Always `apply_patch`. + - `text: optional string` - - `"apply_patch"` + The text that was retrieved from the file. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` - The tool invocation context(s). + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - - `"direct"` + - `id: string` - - `"programmatic"` + The unique ID of the computer call. - - `type: "tool_search_output"` + - `call_id: string` - The type of the item. Always `tool_search_output`. + An identifier used when responding to the tool call with output. - - `"tool_search_output"` + - `pending_safety_checks: array of object { id, code, message }` - - `agent: optional object { agent_name }` + The pending safety checks for the computer call. - 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` - - `created_by: optional string` + The type of the pending safety check. - The identifier of the actor that created the item. + - `message: optional string` - - `AdditionalTools object { id, role, tools, 2 more }` + Details about the pending safety check. - - `id: string` + - `status: "in_progress" or "completed" or "incomplete"` - The unique ID of the additional tools item. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `role: "unknown" or "user" or "assistant" or 5 more` + - `"in_progress"` - The role that provided the additional tools. + - `"completed"` - - `"unknown"` + - `"incomplete"` - - `"user"` + - `type: "computer_call"` - - `"assistant"` + The type of the computer call. Always `computer_call`. - - `"system"` + - `"computer_call"` - - `"critic"` + - `action: optional BetaComputerAction` - - `"discriminator"` + A click action. - - `"developer"` + - `Click object { button, type, x, 2 more }` - - `"tool"` + A click action. - - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` + - `button: "left" or "right" or "wheel" or 2 more` - The additional tool definitions made available at this item. + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `Function object { name, parameters, strict, 5 more }` + - `"left"` - 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). + - `"right"` - - `name: string` + - `"wheel"` - The name of the function to call. + - `"back"` - - `parameters: map[unknown]` + - `"forward"` - A JSON schema object describing the parameters of the function. + - `type: "click"` - - `strict: boolean` + Specifies the event type. For a click action, this property is always `click`. - Whether strict parameter validation is enforced for this function tool. + - `"click"` - - `type: "function"` + - `x: number` - The type of the function tool. Always `function`. + The x-coordinate where the click occurred. - - `"function"` + - `y: number` - - `allowed_callers: optional array of "direct" or "programmatic"` + The y-coordinate where the click occurred. - The tool invocation context(s). + - `keys: optional array of string` - - `"direct"` + The keys being held while clicking. - - `"programmatic"` + - `DoubleClick object { keys, type, x, y }` - - `defer_loading: optional boolean` + A double click action. - Whether this function is deferred and loaded via tool search. + - `keys: array of string` - - `description: optional string` + The keys being held while double-clicking. - A description of the function. Used by the model to determine whether or not to call the function. + - `type: "double_click"` - - `output_schema: optional map[unknown]` + Specifies the event type. For a double click action, this property is always set to `double_click`. - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `"double_click"` - - `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 where the double click occurred. - - `type: "file_search"` + - `y: number` - The type of the file search tool. Always `file_search`. + The y-coordinate where the double click occurred. - - `"file_search"` + - `Drag object { path, type, keys }` - - `vector_store_ids: array of string` + A drag action. - The IDs of the vector stores to search. + - `path: array of object { x, y }` - - `filters: optional object { key, type, value } or object { filters, type }` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - A filter to apply. + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `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. - - `key: string` + - `y: number` - The key to compare against the value. + The y-coordinate. - - `type: "eq" or "ne" or "gt" or 5 more` + - `type: "drag"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + Specifies the event type. For a drag action, this property is always set to `drag`. - - `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"` - - `"eq"` + - `keys: optional array of string` - - `"ne"` + The keys being held while dragging the mouse. - - `"gt"` + - `Keypress object { keys, type }` - - `"gte"` + A collection of keypresses the model would like to perform. - - `"lt"` + - `keys: array of string` - - `"lte"` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `"in"` + - `type: "keypress"` - - `"nin"` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `value: string or number or boolean or array of string or number` + - `"keypress"` - The value to compare against the attribute key; supports string, number, or boolean types. + - `Move object { type, x, y, keys }` - - `string` + A mouse move action. - - `number` + - `type: "move"` - - `boolean` + Specifies the event type. For a move action, this property is always set to `move`. - - `array of string or number` + - `"move"` - - `string` + - `x: number` - - `number` + The x-coordinate to move to. - - `CompoundFilter object { filters, type }` + - `y: number` - Combine multiple filters using `and` or `or`. + The y-coordinate to move to. - - `filters: array of object { key, type, value } or unknown` + - `keys: optional array of string` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + The keys being held while moving the mouse. - - `ComparisonFilter object { key, type, value }` + - `Screenshot object { type }` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + A screenshot action. - - `key: string` + - `type: "screenshot"` - The key to compare against the value. + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `type: "eq" or "ne" or "gt" or 5 more` + - `"screenshot"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `Scroll object { scroll_x, scroll_y, type, 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 + A scroll action. - - `"eq"` + - `scroll_x: number` - - `"ne"` + The horizontal scroll distance. - - `"gt"` + - `scroll_y: number` - - `"gte"` + The vertical scroll distance. - - `"lt"` + - `type: "scroll"` - - `"lte"` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `"in"` + - `"scroll"` - - `"nin"` + - `x: number` - - `value: string or number or boolean or array of string or number` + The x-coordinate where the scroll occurred. - The value to compare against the attribute key; supports string, number, or boolean types. + - `y: number` - - `string` + The y-coordinate where the scroll occurred. - - `number` + - `keys: optional array of string` - - `boolean` + The keys being held while scrolling. - - `array of string or number` + - `Type object { text, type }` - - `string` + An action to type in text. - - `number` + - `text: string` - - `unknown` + The text to type. - - `type: "and" or "or"` + - `type: "type"` - Type of operation: `and` or `or`. + Specifies the event type. For a type action, this property is always set to `type`. - - `"and"` + - `"type"` - - `"or"` + - `Wait object { type }` - - `max_num_results: optional number` + A wait action. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `type: "wait"` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + Specifies the event type. For a wait action, this property is always set to `wait`. - Ranking options for search. + - `"wait"` - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `actions: optional BetaComputerActionList` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `embedding_weight: number` + - `Click object { button, type, x, 2 more }` - The weight of the embedding in the reciprocal ranking fusion. + A click action. - - `text_weight: number` + - `DoubleClick object { keys, type, x, y }` - The weight of the text in the reciprocal ranking fusion. + A double click action. - - `ranker: optional "auto" or "default-2024-11-15"` + - `Drag object { path, type, keys }` - The ranker to use for the file search. + A drag action. - - `"auto"` + - `Keypress object { keys, type }` - - `"default-2024-11-15"` + A collection of keypresses the model would like to perform. - - `score_threshold: optional number` + - `Move object { type, x, y, keys }` - 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 mouse move action. - - `Computer object { 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. - - `type: "computer"` + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - The type of the computer tool. Always `computer`. + A scroll action. - - `"computer"` + - `Type object { text, type }` - - `ComputerUsePreview object { display_height, display_width, environment, 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). + - `Wait object { type }` - - `display_height: number` + A wait action. - 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. + - `ComputerCallOutput object { call_id, output, type, 4 more }` - - `"windows"` + The output of a computer tool call. - - `"mac"` + - `call_id: string` - - `"linux"` + The ID of the computer tool call that produced the output. - - `"ubuntu"` + - `output: BetaResponseComputerToolCallOutputScreenshot` - - `"browser"` + A computer screenshot image used with the computer use tool. - - `type: "computer_use_preview"` + - `type: "computer_screenshot"` - The type of the computer use tool. Always `computer_use_preview`. + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `"computer_use_preview"` + - `"computer_screenshot"` - - `WebSearch object { type, filters, search_context_size, user_location }` + - `file_id: optional string` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The identifier of an uploaded file that contains the screenshot. - - `type: "web_search" or "web_search_2025_08_26"` + - `image_url: optional string` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + The URL of the screenshot image. - - `"web_search"` + - `type: "computer_call_output"` - - `"web_search_2025_08_26"` + The type of the computer tool call output. Always `computer_call_output`. - - `filters: optional object { allowed_domains }` + - `"computer_call_output"` - Filters for the search. + - `id: optional string` - - `allowed_domains: optional array of string` + The ID of the computer tool call output. - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `acknowledged_safety_checks: optional array of object { id, code, message }` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + The safety checks reported by the API that have been acknowledged by the developer. - - `search_context_size: optional "low" or "medium" or "high"` + - `id: string` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + The ID of the pending safety check. - - `"low"` + - `code: optional string` - - `"medium"` + The type of the pending safety check. - - `"high"` + - `message: optional string` - - `user_location: optional object { city, country, region, 2 more }` + Details about the pending safety check. - 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`. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `region: optional string` + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - Free text input for the region of the user, e.g. `California`. + - `"in_progress"` - - `timezone: optional string` + - `"completed"` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `"incomplete"` - - `type: optional "approximate"` + - `WebSearchCall object { id, action, status, 2 more }` - The type of location approximation. Always `approximate`. + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. - - `"approximate"` + - `id: string` - - `Mcp object { server_label, type, allowed_callers, 9 more }` + The unique ID of the web search tool call. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - - `server_label: string` + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). - A label for this MCP server, used to identify it in tool calls. + - `Search object { type, queries, query, sources }` - - `type: "mcp"` + Action type "search" - Performs a web search query. - The type of the MCP tool. Always `mcp`. + - `type: "search"` - - `"mcp"` + The action type. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"search"` - The tool invocation context(s). + - `queries: optional array of string` - - `"direct"` + The search queries. - - `"programmatic"` + - `query: optional string` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + The search query. - List of allowed tool names or a filter object. + - `sources: optional array of object { type, url }` - - `McpAllowedTools = array of string` + The sources used in the search. + + - `type: "url"` + + The type of source. Always `url`. + + - `"url"` + + - `url: string` + + The URL of the source. - A string array of allowed tool names + - `OpenPage object { type, url }` - - `McpToolFilter 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. - - `authorization: optional string` + - `FindInPage object { pattern, type, url }` - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. + Action type "find_in_page": Searches for a pattern within a loaded page. - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + - `pattern: 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + The pattern or text to search for within the page. - Currently supported `connector_id` values are: + - `type: "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` + The action type. - - `"connector_dropbox"` + - `"find_in_page"` - - `"connector_gmail"` + - `url: string` - - `"connector_googlecalendar"` + The URL of the page searched for the pattern. - - `"connector_googledrive"` + - `status: "in_progress" or "searching" or "completed" or "failed"` - - `"connector_microsoftteams"` + The status of the web search tool call. - - `"connector_outlookcalendar"` + - `"in_progress"` - - `"connector_outlookemail"` + - `"searching"` - - `"connector_sharepoint"` + - `"completed"` - - `defer_loading: optional boolean` + - `"failed"` - Whether this MCP tool is deferred and discovered via tool search. + - `type: "web_search_call"` - - `headers: optional map[string]` + The type of the web search tool call. Always `web_search_call`. - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `"web_search_call"` - - `require_approval: optional object { always, never } or "always" or "never"` + - `agent: optional object { agent_name }` - Specify which of the MCP server's tools require approval. + The agent that produced this item. - - `McpToolApprovalFilter object { always, never }` + - `agent_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 canonical name of the agent that produced this item. - - `always: optional object { read_only, tool_names }` + - `FunctionCall object { arguments, call_id, name, 6 more }` - A filter object to specify which tools are allowed. + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. - - `read_only: optional boolean` + - `arguments: 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 arguments to pass to the function. - - `tool_names: optional array of string` + - `call_id: string` - List of allowed tool names. + The unique ID of the function tool call generated by the model. - - `never: optional object { read_only, tool_names }` + - `name: string` - A filter object to specify which tools are allowed. + The name of the function to run. - - `read_only: optional boolean` + - `type: "function_call"` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + The type of the function tool call. Always `function_call`. - - `tool_names: optional array of string` + - `"function_call"` - List of allowed tool names. + - `id: optional string` - - `McpToolApprovalSetting = "always" or "never"` + The unique ID of the function 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. + - `agent: optional object { agent_name }` - - `"always"` + The agent that produced this item. - - `"never"` + - `agent_name: string` - - `server_description: optional string` + The canonical name of the agent that produced this item. - Optional description of the MCP server, used to provide more context. + - `caller: optional object { type } or object { caller_id, type }` - - `server_url: optional string` + The execution context that produced this tool call. - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `Direct object { type }` - - `tunnel_id: optional string` + - `type: "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` + - `"program"` - The container ID. + - `namespace: optional string` - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + The namespace of the function to run. - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `type: "auto"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Always `auto`. + - `"in_progress"` - - `"auto"` + - `"completed"` - - `file_ids: optional array of string` + - `"incomplete"` - An optional list of uploaded files to make available to your code. + - `FunctionCallOutput object { call_id, output, type, 4 more }` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + The output of a function tool call. - The memory limit for the code interpreter container. + - `call_id: string` - - `"1g"` + The unique ID of the function tool call generated by the model. - - `"4g"` + - `output: string or array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` - - `"16g"` + Text, image, or file output of the function tool call. - - `"64g"` + - `string` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + A JSON string of the output of the function tool call. - Network access policy for the container. + - `array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` - - `BetaContainerNetworkPolicyDisabled object { type }` + An array of content outputs (text, image, file) for the function tool call. - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` - - `type: "code_interpreter"` + A text input to the model. - The type of the code interpreter tool. Always `code_interpreter`. + - `text: string` - - `"code_interpreter"` + The text input to the model. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `type: "input_text"` - The tool invocation context(s). + The type of the input item. Always `input_text`. - - `"direct"` + - `"input_text"` - - `"programmatic"` + - `prompt_cache_breakpoint: optional object { mode }` - - `ProgrammaticToolCalling 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: "programmatic_tool_calling"` + - `mode: "explicit"` - The type of the tool. Always `programmatic_tool_calling`. + The breakpoint mode. Always `explicit`. - - `"programmatic_tool_calling"` + - `"explicit"` - - `ImageGeneration object { type, action, background, 9 more }` + - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` - A tool that generates images using the GPT image models. + An image input to the model. Learn about [image inputs](/docs/guides/vision) - - `type: "image_generation"` + - `type: "input_image"` - The type of the image generation tool. Always `image_generation`. + The type of the input item. Always `input_image`. - - `"image_generation"` + - `"input_image"` - - `action: optional "generate" or "edit" or "auto"` + - `detail: optional "low" or "high" or "auto" or "original"` - Whether to generate a new image or edit an existing 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`. - - `"generate"` + - `"low"` - - `"edit"` + - `"high"` - `"auto"` - - `background: optional "transparent" or "opaque" or "auto"` - - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + - `"original"` - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + - `file_id: optional string` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + The ID of the file to be sent to the model. - - `"transparent"` + - `image_url: optional string` - - `"opaque"` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `"auto"` + - `prompt_cache_breakpoint: optional object { mode }` - - `input_fidelity: optional "high" or "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. - 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`. + - `mode: "explicit"` - - `"high"` + The breakpoint mode. Always `explicit`. - - `"low"` + - `"explicit"` - - `input_image_mask: optional object { file_id, image_url }` + - `BetaResponseInputFileContent object { type, detail, file_data, 4 more }` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + A file input to the model. - - `file_id: optional string` + - `type: "input_file"` - File ID for the mask image. + The type of the input item. Always `input_file`. - - `image_url: optional string` + - `"input_file"` - Base64-encoded mask image. + - `detail: optional "auto" or "low" or "high"` - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 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`. - The image generation model to use. Default: `gpt-image-1`. + - `"auto"` - - `string` + - `"low"` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `"high"` - The image generation model to use. Default: `gpt-image-1`. + - `file_data: optional string` - - `"gpt-image-1"` + The base64-encoded data of the file to be sent to the model. - - `"gpt-image-1-mini"` + - `file_id: optional string` - - `"gpt-image-2"` + The ID of the file to be sent to the model. - - `"gpt-image-2-2026-04-21"` + - `file_url: optional string` - - `"gpt-image-1.5"` + The URL of the file to be sent to the model. - - `"chatgpt-image-latest"` + - `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](https://platform.openai.com/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 array of object { end_index, start_index, title, 2 more } or array of 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. + - `array of 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](https://platform.openai.com/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"` + - `array of 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"` + - `array of 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"` @@ -184101,1172 +183841,1166 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"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` + - `defer_loading: optional boolean` - The canonical name of the agent that produced this item. + Whether this function is deferred and loaded via tool search. - - `Compaction object { id, encrypted_content, type, 2 more }` + - `description: optional string` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + 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 compaction item. + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `encrypted_content: string` + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - The encrypted content that was produced by 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). - - `type: "compaction"` + - `type: "file_search"` - The type of the item. Always `compaction`. + The type of the file search tool. Always `file_search`. - - `"compaction"` + - `"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. - - `created_by: optional string` + - `ComparisonFilter object { key, type, value }` - The identifier of the actor that created the item. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `ImageGenerationCall object { id, result, status, 2 more }` + - `key: string` - An image generation request made by the model. + The key to compare against the value. - - `id: string` + - `type: "eq" or "ne" or "gt" or 5 more` - The unique ID of the image generation call. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `result: 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 generated image encoded in base64. + - `"eq"` - - `status: "in_progress" or "completed" or "generating" or "failed"` + - `"ne"` - The status of the image generation call. + - `"gt"` - - `"in_progress"` + - `"gte"` - - `"completed"` + - `"lt"` - - `"generating"` + - `"lte"` - - `"failed"` + - `"in"` - - `type: "image_generation_call"` + - `"nin"` - The type of the image generation call. Always `image_generation_call`. + - `value: string or number or boolean or array of string or number` - - `"image_generation_call"` + The value to compare against the attribute key; supports string, number, or boolean types. - - `agent: optional object { agent_name }` + - `string` - The agent that produced this item. + - `number` - - `agent_name: string` + - `boolean` - The canonical name of the agent that produced this item. + - `array of string or number` - - `CodeInterpreterCall object { id, code, container_id, 4 more }` + - `string` - A tool call to run code. + - `number` - - `id: string` + - `CompoundFilter object { filters, type }` - The unique ID of the code interpreter tool call. + Combine multiple filters using `and` or `or`. - - `code: string` + - `filters: array of object { key, type, value } or unknown` - The code to run, or null if not available. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `container_id: string` + - `ComparisonFilter object { key, type, value }` - The ID of the container used to run the code. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `outputs: array of object { logs, type } or object { type, url }` + - `key: string` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + The key to compare against the value. - - `Logs object { logs, type }` + - `type: "eq" or "ne" or "gt" or 5 more` - The logs output from the code interpreter. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `logs: 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 logs output from the code interpreter. + - `"eq"` - - `type: "logs"` + - `"ne"` - The type of the output. Always `logs`. + - `"gt"` - - `"logs"` + - `"gte"` - - `Image object { type, url }` + - `"lt"` - The image output from the code interpreter. + - `"lte"` - - `type: "image"` + - `"in"` - The type of the output. Always `image`. + - `"nin"` - - `"image"` + - `value: string or number or boolean or array of string or number` - - `url: string` + The value to compare against the attribute key; supports string, number, or boolean types. - The URL of the image output from the code interpreter. + - `string` - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + - `number` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `boolean` - - `"in_progress"` + - `array of string or number` - - `"completed"` + - `string` - - `"incomplete"` + - `number` - - `"interpreting"` + - `unknown` - - `"failed"` + - `type: "and" or "or"` - - `type: "code_interpreter_call"` + Type of operation: `and` or `or`. - The type of the code interpreter tool call. Always `code_interpreter_call`. + - `"and"` - - `"code_interpreter_call"` + - `"or"` - - `agent: optional object { agent_name }` + - `max_num_results: optional number` - The agent that produced this item. + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `agent_name: string` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - The canonical name of the agent that produced this item. + Ranking options for search. - - `LocalShellCall object { id, action, call_id, 3 more }` + - `hybrid_search: optional object { embedding_weight, text_weight }` - A tool call to run a command on the local shell. + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `id: string` + - `embedding_weight: number` - The unique ID of the local shell call. + The weight of the embedding in the reciprocal ranking fusion. - - `action: object { command, env, type, 3 more }` + - `text_weight: number` - Execute a shell command on the server. + The weight of the text in the reciprocal ranking fusion. - - `command: array of string` + - `ranker: optional "auto" or "default-2024-11-15"` - The command to run. + The ranker to use for the file search. - - `env: map[string]` + - `"auto"` - Environment variables to set for the command. + - `"default-2024-11-15"` - - `type: "exec"` + - `score_threshold: optional number` - The type of the local shell action. Always `exec`. + 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. - - `"exec"` + - `Computer object { type }` - - `timeout_ms: optional number` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - Optional timeout in milliseconds for the command. + - `type: "computer"` - - `user: optional string` + The type of the computer tool. Always `computer`. - Optional user to run the command as. + - `"computer"` - - `working_directory: optional string` + - `ComputerUsePreview object { display_height, display_width, environment, type }` - Optional working directory to run the command in. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `call_id: string` + - `display_height: number` - The unique ID of the local shell tool call generated by the model. + The height of the computer display. - - `status: "in_progress" or "completed" or "incomplete"` + - `display_width: number` - The status of the local shell call. + 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"` - - `type: "local_shell_call"` + - `"mac"` - The type of the local shell call. Always `local_shell_call`. + - `"linux"` - - `"local_shell_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"` - - `LocalShellCallOutput object { id, output, type, 2 more }` + - `WebSearch object { type, filters, search_context_size, user_location }` - The output of a local shell tool call. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - - `id: string` + - `type: "web_search" or "web_search_2025_08_26"` - The unique ID of the local shell tool call generated by the model. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `output: string` + - `"web_search"` - A JSON string of the output of the local shell tool call. + - `"web_search_2025_08_26"` - - `type: "local_shell_call_output"` + - `filters: optional object { allowed_domains }` - The type of the local shell tool call output. Always `local_shell_call_output`. + Filters for the search. - - `"local_shell_call_output"` + - `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 item. One of `in_progress`, `completed`, or `incomplete`. + - `"medium"` - - `"in_progress"` + - `"high"` - - `"completed"` + - `user_location: optional object { city, country, region, 2 more }` - - `"incomplete"` + The approximate location of the user. - - `ShellCall object { id, action, call_id, 6 more }` + - `city: optional string` - A tool call that executes one or more shell commands in a managed environment. + Free text input for the city of the user, e.g. `San Francisco`. - - `id: string` + - `country: optional string` - The unique ID of the shell tool call. Populated when this item is returned via API. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `action: object { commands, max_output_length, timeout_ms }` + - `region: optional string` - The shell commands and limits that describe how to run the tool call. + Free text input for the region of the user, e.g. `California`. - - `commands: array of string` + - `timezone: optional string` - - `max_output_length: number` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - Optional maximum number of characters to return from each command. + - `type: optional "approximate"` - - `timeout_ms: number` + The type of location approximation. Always `approximate`. - Optional timeout in milliseconds for the commands. + - `"approximate"` - - `call_id: string` + - `Mcp object { server_label, type, allowed_callers, 9 more }` - The unique ID of the shell tool call generated by the model. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` + - `server_label: string` - Represents the use of a local environment to perform shell actions. + A label for this MCP server, used to identify it in tool calls. - - `BetaResponseLocalEnvironment object { type }` + - `type: "mcp"` - Represents the use of a local environment to perform shell actions. + The type of the MCP tool. Always `mcp`. - - `type: "local"` + - `"mcp"` - The environment type. Always `local`. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"local"` + The tool invocation context(s). - - `BetaResponseContainerReference object { container_id, type }` + - `"direct"` - Represents a container created with /v1/containers. + - `"programmatic"` - - `container_id: string` + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `type: "container_reference"` + List of allowed tool names or a filter object. - The environment type. Always `container_reference`. + - `McpAllowedTools = array of string` - - `"container_reference"` + A string array of allowed tool names - - `status: "in_progress" or "completed" or "incomplete"` + - `McpToolFilter object { read_only, tool_names }` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + A filter object to specify which tools are allowed. - - `"in_progress"` + - `read_only: optional boolean` - - `"completed"` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `"incomplete"` + - `tool_names: optional array of string` - - `type: "shell_call"` + List of allowed tool names. - The type of the item. Always `shell_call`. + - `authorization: optional string` - - `"shell_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. - - `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"` - - `"direct"` + - `"connector_microsoftteams"` - - `Program object { caller_id, type }` + - `"connector_outlookcalendar"` - - `caller_id: string` + - `"connector_outlookemail"` - The call ID of the program item that produced this tool call. + - `"connector_sharepoint"` - - `type: "program"` + - `defer_loading: optional boolean` - - `"program"` + Whether this MCP tool is deferred and discovered via tool search. - - `created_by: optional string` + - `headers: optional map[string]` - The ID of the entity that created this tool call. + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `ShellCallOutput object { id, call_id, max_output_length, 6 more }` + - `require_approval: optional object { always, never } or "always" or "never"` - The output of a shell tool call that was emitted. + Specify which of the MCP server's tools require approval. - - `id: string` + - `McpToolApprovalFilter object { always, never }` - The unique ID of the shell call output. Populated when this item is returned via API. + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `call_id: string` + - `always: optional object { read_only, tool_names }` - The unique ID of the 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 }` + - `never: optional 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"` + - `McpToolApprovalSetting = "always" or "never"` - - `Exit object { exit_code, 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. - Indicates that the shell commands finished and returned an exit code. + - `"always"` - - `exit_code: number` + - `"never"` - Exit code from the shell process. + - `server_description: optional string` - - `type: "exit"` + Optional description of the MCP server, used to provide more context. - The outcome type. Always `exit`. + - `server_url: optional string` - - `"exit"` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `stderr: string` + - `tunnel_id: optional string` - The standard error output that was captured. + 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. - - `stdout: string` + - `CodeInterpreter object { container, type, allowed_callers }` - The standard output that was captured. + A tool that runs Python code to help generate a response to a prompt. - - `created_by: optional string` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - The identifier of the actor that created the item. + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - - `status: "in_progress" or "completed" or "incomplete"` + - `string` - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + The container ID. - - `"in_progress"` + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - - `"completed"` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `"incomplete"` + - `type: "auto"` - - `type: "shell_call_output"` + Always `auto`. - The type of the shell call output. Always `shell_call_output`. + - `"auto"` - - `"shell_call_output"` + - `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` - - `"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"` - - `"program"` + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `created_by: optional string` + - `allowed_domains: array of string` - The identifier of the actor that created the item. + A list of allowed domains when type is `allowlist`. - - `ApplyPatchCall object { id, call_id, operation, 5 more }` + - `type: "allowlist"` - A tool call that applies file diffs by creating, deleting, or updating files. + Allow outbound network access only to specified domains. Always `allowlist`. - - `id: string` + - `"allowlist"` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` - - `call_id: string` + Optional domain-scoped secrets for allowlisted domains. - The unique ID of the apply patch tool call generated by the model. + - `domain: string` - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + The domain associated with the secret. - One of the create_file, delete_file, or update_file operations applied via apply_patch. + - `name: string` - - `CreateFile object { diff, path, type }` + The name of the secret to inject for the domain. - Instruction describing how to create a file via the apply_patch tool. + - `value: string` - - `diff: string` + The secret value to inject for the domain. - Diff to apply. + - `type: "code_interpreter"` - - `path: string` + The type of the code interpreter tool. Always `code_interpreter`. - Path of the file to create. + - `"code_interpreter"` - - `type: "create_file"` + - `allowed_callers: optional array of "direct" or "programmatic"` - Create a new file with the provided diff. + The tool invocation context(s). - - `"create_file"` + - `"direct"` - - `DeleteFile object { path, type }` + - `"programmatic"` - Instruction describing how to delete a file via the apply_patch tool. + - `ProgrammaticToolCalling object { type }` - - `path: string` + - `type: "programmatic_tool_calling"` - Path of the file to delete. + The type of the tool. Always `programmatic_tool_calling`. - - `type: "delete_file"` + - `"programmatic_tool_calling"` - Delete the specified file. + - `ImageGeneration object { type, action, background, 9 more }` - - `"delete_file"` + A tool that generates images using the GPT image models. - - `UpdateFile object { diff, path, type }` + - `type: "image_generation"` - Instruction describing how to update a file via the apply_patch tool. + The type of the image generation tool. Always `image_generation`. - - `diff: string` + - `"image_generation"` - Diff to apply. + - `action: optional "generate" or "edit" or "auto"` - - `path: string` + Whether to generate a new image or edit an existing image. Default: `auto`. - Path of the file to update. + - `"generate"` - - `type: "update_file"` + - `"edit"` - Update an existing file with the provided diff. + - `"auto"` - - `"update_file"` + - `background: optional "transparent" or "opaque" or "auto"` - - `status: "in_progress" or "completed"` + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `"transparent"` - - `"in_progress"` + - `"opaque"` - - `"completed"` + - `"auto"` - - `type: "apply_patch_call"` + - `input_fidelity: optional "high" or "low"` - The type of the item. Always `apply_patch_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`. - - `"apply_patch_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` - - `caller: optional object { type } or object { caller_id, type }` + File ID for the mask image. - The execution context that produced this tool call. + - `image_url: optional string` - - `Direct object { type }` + Base64-encoded mask image. - - `type: "direct"` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `"direct"` + The image generation model to use. Default: `gpt-image-1`. - - `Program object { caller_id, type }` + - `string` - - `caller_id: string` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - The call ID of the program item that produced this tool call. + The image generation model to use. Default: `gpt-image-1`. - - `type: "program"` + - `"gpt-image-1"` - - `"program"` + - `"gpt-image-1-mini"` - - `created_by: optional string` + - `"gpt-image-1.5"` - The ID of the entity that created this tool call. + - `moderation: optional "auto" or "low"` - - `ApplyPatchCallOutput object { id, call_id, status, 5 more }` + Moderation level for the generated image. Default: `auto`. - The output emitted by an apply patch tool call. + - `"auto"` - - `id: string` + - `"low"` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `output_compression: optional number` - - `call_id: string` + Compression level for the output image. Default: 100. - The unique ID of the apply patch tool call generated by the model. + - `output_format: optional "png" or "webp" or "jpeg"` - - `status: "completed" or "failed"` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - The status of the apply patch tool call output. One of `completed` or `failed`. + - `"png"` - - `"completed"` + - `"webp"` - - `"failed"` + - `"jpeg"` - - `type: "apply_patch_call_output"` + - `partial_images: optional number` - The type of the item. Always `apply_patch_call_output`. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `"apply_patch_call_output"` + - `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"` - - `caller: optional object { type } or object { caller_id, type }` + - `"auto"` - The execution context that produced this tool call. + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `Direct object { type }` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `type: "direct"` + - `string` - - `"direct"` + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `Program object { caller_id, type }` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `caller_id: string` + - `"1024x1024"` - The call ID of the program item that produced this tool call. + - `"1024x1536"` - - `type: "program"` + - `"1536x1024"` - - `"program"` + - `"auto"` - - `created_by: optional string` + - `LocalShell object { type }` - The ID of the entity that created this tool call output. + A tool that allows the model to execute shell commands in a local environment. - - `output: optional string` + - `type: "local_shell"` - Optional textual output returned by the apply patch tool. + The type of the local shell tool. Always `local_shell`. - - `McpCall object { id, arguments, name, 7 more }` + - `"local_shell"` - An invocation of a tool on an MCP server. + - `Shell object { type, allowed_callers, environment }` - - `id: string` + A tool that allows the model to execute shell commands. - The unique ID of the tool call. + - `type: "shell"` - - `arguments: string` + The type of the shell tool. Always `shell`. - A JSON string of the arguments passed to the tool. + - `"shell"` - - `name: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The name of the tool that was run. + The tool invocation context(s). - - `server_label: string` + - `"direct"` - The label of the MCP server running the tool. + - `"programmatic"` - - `type: "mcp_call"` + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - The type of the item. Always `mcp_call`. + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - - `"mcp_call"` + - `type: "container_auto"` - - `agent: optional object { agent_name }` + Automatically creates a container for this request - The agent that produced this item. + - `"container_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. - - `approval_request_id: optional string` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - 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 memory limit for the container. - - `error: optional string` + - `"1g"` - The error from the tool call, if any. + - `"4g"` - - `output: optional string` + - `"16g"` - The output from the tool call. + - `"64g"` - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + Network access policy for the container. - - `"in_progress"` + - `BetaContainerNetworkPolicyDisabled object { type }` - - `"completed"` + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `"incomplete"` + - `skills: optional array of BetaSkillReference or BetaInlineSkill` - - `"calling"` + An optional list of skills referenced by id or inline data. - - `"failed"` + - `BetaSkillReference object { skill_id, type, version }` - - `McpListTools object { id, server_label, tools, 3 more }` + - `skill_id: string` - A list of tools available on an MCP server. + The ID of the referenced skill. - - `id: string` + - `type: "skill_reference"` - The unique ID of the list. + References a skill created with the /v1/skills endpoint. - - `server_label: string` + - `"skill_reference"` - The label of the MCP server. + - `version: optional string` - - `tools: array of object { input_schema, name, annotations, description }` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - The tools available on the server. + - `BetaInlineSkill object { description, name, source, type }` - - `input_schema: unknown` + - `description: string` - The JSON schema describing the tool's input. + The description of the skill. - `name: string` - The name of the tool. - - - `annotations: optional unknown` - - Additional annotations about the tool. + The name of the skill. - - `description: optional string` + - `source: BetaInlineSkillSource` - The description of the tool. + Inline skill payload - - `type: "mcp_list_tools"` + - `data: string` - The type of the item. Always `mcp_list_tools`. + Base64-encoded skill zip bundle. - - `"mcp_list_tools"` + - `media_type: "application/zip"` - - `agent: optional object { agent_name }` + The media type of the inline skill payload. Must be `application/zip`. - The agent that produced this item. + - `"application/zip"` - - `agent_name: string` + - `type: "base64"` - The canonical name of the agent that produced this item. + The type of the inline skill source. Must be `base64`. - - `error: optional string` + - `"base64"` - Error message if the server could not list tools. + - `type: "inline"` - - `McpApprovalRequest object { id, arguments, name, 3 more }` + Defines an inline skill for this request. - A request for human approval of a tool invocation. + - `"inline"` - - `id: string` + - `BetaLocalEnvironment object { type, skills }` - The unique ID of the approval request. + - `type: "local"` - - `arguments: string` + Use a local computer environment. - A JSON string of arguments for the tool. + - `"local"` - - `name: string` + - `skills: optional array of BetaLocalSkill` - The name of the tool to run. + An optional list of skills. - - `server_label: string` + - `description: string` - The label of the MCP server making the request. + The description of the skill. - - `type: "mcp_approval_request"` + - `name: string` - The type of the item. Always `mcp_approval_request`. + The name of the skill. - - `"mcp_approval_request"` + - `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. - - `McpApprovalResponse object { id, approval_request_id, approve, 3 more }` + - `type: "container_reference"` - A response to an MCP approval request. + References a container created with the /v1/containers endpoint - - `id: string` + - `"container_reference"` - The unique ID of the approval response + - `Custom object { name, type, allowed_callers, 3 more }` - - `approval_request_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 approval request being answered. + - `name: string` - - `approve: boolean` + The name of the custom tool, used to identify it in tool calls. - Whether the request was approved. + - `type: "custom"` - - `type: "mcp_approval_response"` + The type of the custom tool. Always `custom`. - The type of the item. Always `mcp_approval_response`. + - `"custom"` - - `"mcp_approval_response"` + - `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` - - `reason: optional string` + Whether this tool should be deferred and discovered via tool search. - Optional reason for the decision. + - `description: optional string` - - `CustomToolCall object { call_id, input, name, 5 more }` + Optional description of the custom tool, used to provide more context. - A call to a custom tool created by the model. + - `format: optional object { type } or object { definition, syntax, type }` - - `call_id: string` + The input format for the custom tool. Default is unconstrained text. - An identifier used to map this custom tool call to a tool call output. + - `Text object { type }` - - `input: string` + Unconstrained free-form text. - The input for the custom tool call generated by the model. + - `type: "text"` - - `name: string` + Unconstrained text format. Always `text`. - The name of the custom tool being called. + - `"text"` - - `type: "custom_tool_call"` + - `Grammar object { definition, syntax, type }` - The type of the custom tool call. Always `custom_tool_call`. + A grammar defined by the user. - - `"custom_tool_call"` + - `definition: string` - - `id: optional string` + The grammar definition. - The unique ID of the custom tool call in the OpenAI platform. + - `syntax: "lark" or "regex"` - - `agent: optional object { agent_name }` + The syntax of the grammar definition. One of `lark` or `regex`. - The agent that produced this item. + - `"lark"` - - `agent_name: string` + - `"regex"` - The canonical name of the agent that produced this item. + - `type: "grammar"` - - `caller: optional object { type } or object { caller_id, type }` + Grammar format. Always `grammar`. - The execution context that produced this tool call. + - `"grammar"` - - `Direct object { type }` + - `Namespace object { description, name, tools, type }` - - `type: "direct"` + Groups function/custom tools under a shared namespace. - - `"direct"` + - `description: string` - - `Program object { caller_id, type }` + A description of the namespace shown to the model. - - `caller_id: string` + - `name: string` - The call ID of the program item that produced this tool call. + The namespace name used in tool calls (for example, `crm`). - - `type: "program"` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - - `"program"` + The function/custom tools available inside this namespace. - - `namespace: optional string` + - `Function object { name, type, allowed_callers, 5 more }` - The namespace of the custom tool being called. + - `name: string` - - `CustomToolCallOutput object { id, call_id, output, 5 more }` + - `type: "function"` - - `id: string` + - `"function"` - The unique ID of the custom tool call output item. + - `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` + - `"programmatic"` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `defer_loading: optional boolean` - - `StringOutput = string` + Whether this function should be deferred and discovered via tool search. - A string of the output of the custom tool call. + - `description: optional string` - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `output_schema: optional map[unknown]` - Text, image, or file output of the custom tool call. + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `parameters: optional unknown` - A text input to the model. + - `strict: optional boolean` - - `BetaResponseInputImage object { detail, type, file_id, 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. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `Custom object { name, type, allowed_callers, 3 more }` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - A file input to the model. + - `name: string` - - `status: "in_progress" or "completed" or "incomplete"` + The name of the custom tool, used to identify it in tool calls. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `type: "custom"` - - `"in_progress"` + The type of the custom tool. Always `custom`. - - `"completed"` + - `"custom"` - - `"incomplete"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `type: "custom_tool_call_output"` + The tool invocation context(s). - The type of the custom tool call output. Always `custom_tool_call_output`. + - `"direct"` - - `"custom_tool_call_output"` + - `"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. - The caller type. Always `direct`. + - `type: "text"` - - `"direct"` + Unconstrained text format. Always `text`. - - `Program object { caller_id, type }` + - `"text"` - - `caller_id: string` + - `Grammar object { definition, syntax, type }` - The call ID of the program item that produced this tool call. + A grammar defined by the user. - - `type: "program"` + - `definition: string` - The caller type. Always `program`. + The grammar definition. - - `"program"` + - `syntax: "lark" or "regex"` - - `created_by: optional string` + The syntax of the grammar definition. One of `lark` or `regex`. - The identifier of the actor that created the item. + - `"lark"` - - `parallel_tool_calls: boolean` + - `"regex"` - Whether to allow the model to run tool calls in parallel. + - `type: "grammar"` - - `temperature: number` + Grammar format. Always `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"` - - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` + - `type: "namespace"` - 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 `namespace`. - - `BetaToolChoiceOptions = "none" or "auto" or "required"` + - `"namespace"` - Controls which (if any) tool is called by the model. + - `ToolSearch object { type, description, execution, parameters }` - `none` means the model will not call any tool and instead generates a message. + Hosted or BYOT tool search configuration for deferred tools. - `auto` means the model can pick between generating a message or calling one or - more tools. + - `type: "tool_search"` - `required` means the model must call one or more tools. + The type of the tool. Always `tool_search`. - - `"none"` + - `"tool_search"` - - `"auto"` + - `description: optional string` - - `"required"` + Description shown to the model for a client-executed tool search tool. - - `BetaToolChoiceAllowed object { mode, tools, type }` + - `execution: optional "server" or "client"` - Constrains the tools available to the model to a pre-defined set. + Whether tool search is executed by the server or by the client. - - `mode: "auto" or "required"` + - `"server"` - Constrains the tools available to the model to a pre-defined set. + - `"client"` - `auto` allows the model to pick from among the allowed tools and generate a - message. + - `parameters: optional unknown` - `required` requires the model to call one or more of the allowed tools. + Parameter schema for a client-executed tool search tool. - - `"auto"` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - - `"required"` + 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). - - `tools: array of map[unknown]` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - A list of tool definitions that the model should be allowed to call. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - For the Responses API, the list of tool definitions might look like: + - `"web_search_preview"` - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + - `"web_search_preview_2025_03_11"` - - `type: "allowed_tools"` + - `search_content_types: optional array of "text" or "image"` - Allowed tool configuration type. Always `allowed_tools`. + - `"text"` - - `"allowed_tools"` + - `"image"` - - `BetaToolChoiceTypes object { type }` + - `search_context_size: optional "low" or "medium" or "high"` - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + 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" or "web_search_preview" or "computer" or 5 more` + - `"low"` - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + - `"medium"` - Allowed values are: + - `"high"` - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + - `user_location: optional object { type, city, country, 2 more }` - - `"file_search"` + The user's location. - - `"web_search_preview"` + - `type: "approximate"` - - `"computer"` + The type of location approximation. Always `approximate`. - - `"computer_use_preview"` + - `"approximate"` - - `"computer_use"` + - `city: optional string` - - `"web_search_preview_2025_03_11"` + Free text input for the city of the user, e.g. `San Francisco`. - - `"image_generation"` + - `country: optional string` - - `"code_interpreter"` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `BetaToolChoiceFunction object { name, type }` + - `region: optional string` - Use this option to force the model to call a specific function. + Free text input for the region of the user, e.g. `California`. - - `name: string` + - `timezone: optional string` - The name of the function to call. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `type: "function"` + - `ApplyPatch object { type, allowed_callers }` - For function calling, the type is always `function`. + Allows the assistant to create, delete, or update files using unified diffs. - - `"function"` + - `type: "apply_patch"` - - `BetaToolChoiceMcp object { server_label, type, name }` + The type of the tool. Always `apply_patch`. - Use this option to force the model to call a specific tool on a remote MCP server. + - `"apply_patch"` - - `server_label: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The label of the MCP server to use. + The tool invocation context(s). - - `type: "mcp"` + - `"direct"` - For MCP tools, the type is always `mcp`. + - `"programmatic"` - - `"mcp"` + - `type: "tool_search_output"` - - `name: optional string` + The item type. Always `tool_search_output`. - The name of the tool to call on the server. + - `"tool_search_output"` - - `BetaToolChoiceCustom object { name, type }` + - `id: optional string` - Use this option to force the model to call a specific custom tool. + The unique ID of this tool search output. - - `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"` + - `call_id: optional string` - - `BetaSpecificProgrammaticToolCallingParam object { type }` + The unique ID of the tool search call generated by the model. - - `type: "programmatic_tool_calling"` + - `execution: optional "server" or "client"` - The tool to call. Always `programmatic_tool_calling`. + Whether tool search was executed by the server or by the client. - - `"programmatic_tool_calling"` + - `"server"` - - `BetaToolChoiceApplyPatch object { type }` + - `"client"` - Forces the model to call the apply_patch tool when executing a tool call. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `type: "apply_patch"` + The status of the tool search output. - The tool to call. Always `apply_patch`. + - `"in_progress"` - - `"apply_patch"` + - `"completed"` - - `BetaToolChoiceShell object { type }` + - `"incomplete"` - Forces the model to call the shell tool when a tool call is required. + - `AdditionalTools object { role, tools, type, 2 more }` - - `type: "shell"` + - `role: "developer"` - The tool to call. Always `shell`. + The role that provided the additional tools. Only `developer` is supported. - - `"shell"` + - `"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` - 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](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/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](https://platform.openai.com/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](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. + A list of additional tools made available at this item. - `Function object { name, parameters, strict, 5 more }` @@ -185529,7 +185263,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-web-search). + [web search tool](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -185589,7 +185323,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -185641,7 +185375,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -185833,19 +185567,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `background: optional "transparent" or "opaque" or "auto"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. - - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. - - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - `"transparent"` @@ -185874,13 +185597,13 @@ curl -X POST https://api.openai.com/v1/responses/compact \ Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `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-2" or 3 more` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` The image generation model to use. Default: `gpt-image-1`. @@ -185888,14 +185611,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"gpt-image-1-mini"` - - `"gpt-image-2"` - - - `"gpt-image-2-2026-04-21"` - - `"gpt-image-1.5"` - - `"chatgpt-image-latest"` - - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -185992,7 +185709,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -186106,7 +185823,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -186274,4154 +185991,4299 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"programmatic"` - - `top_p: number` + - `type: "additional_tools"` - An alternative to sampling with temperature, called nucleus sampling, - where the model considers the results of the tokens with top_p probability - mass. So 0.1 means only the tokens comprising the top 10% probability mass - are considered. + The item type. Always `additional_tools`. - We generally recommend altering this or `temperature` but not both. + - `"additional_tools"` - - `background: optional boolean` + - `id: optional string` - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + The unique ID of this additional tools item. - - `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. + + - `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 ID of the conversation that this response was associated with. + The unique identifier of the reasoning content. - - `max_output_tokens: optional number` + - `summary: array of object { text, type }` - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + Reasoning summary content. - - `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. + A summary of the reasoning output from the model so far. - - `moderation: optional object { input, output }` + - `type: "summary_text"` - Moderation results for the response input and output, if moderated completions were requested. + The type of the object. Always `summary_text`. - - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + - `"summary_text"` - Moderation for the response input. + - `type: "reasoning"` - - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` + The type of the object. Always `reasoning`. - A moderation result produced for the response input or output. + - `"reasoning"` - - `categories: map[boolean]` + - `agent: optional object { agent_name }` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + The agent that produced this item. - - `category_applied_input_types: map[array of "text" or "image"]` + - `agent_name: string` - Which modalities of input are reflected by the score for each category. + The canonical name of the agent that produced this item. - - `"text"` + - `content: optional array of object { text, type }` - - `"image"` + Reasoning text content. - - `category_scores: map[number]` + - `text: string` - A dictionary of moderation categories to scores. + The reasoning text from the model. - - `flagged: boolean` + - `type: "reasoning_text"` - A boolean indicating whether the content was flagged by any category. + The type of the reasoning text. Always `reasoning_text`. - - `model: string` + - `"reasoning_text"` - The moderation model that produced this result. + - `encrypted_content: optional string` - - `type: "moderation_result"` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - The object type, which was always `moderation_result` for successful moderation results. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"moderation_result"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `Error object { code, message, type }` + - `"in_progress"` - An error produced while attempting moderation for the response input or output. + - `"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 error code. + The code to run, or null if not available. - - `message: string` + - `container_id: string` - The error message. + The ID of the container used to run the code. - - `type: "error"` + - `outputs: array of object { logs, type } or object { type, url }` - The object type, which was always `error` for moderation failures. + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `"error"` + - `Logs object { logs, type }` - - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + The logs output from the code interpreter. - Moderation for the response output. + - `logs: string` - - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` + The logs output from the code interpreter. - A moderation result produced for the response input or output. + - `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. - - `categories: map[boolean]` + - `LocalShellCall object { id, action, call_id, 3 more }` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + A tool call to run a command on the local shell. - - `category_applied_input_types: map[array of "text" or "image"]` + - `id: string` - Which modalities of input are reflected by the score for each category. + The unique ID of the local shell call. - - `"text"` + - `action: object { command, env, type, 3 more }` - - `"image"` + Execute a shell command on the server. - - `category_scores: map[number]` + - `command: array of string` - A dictionary of moderation categories to scores. + The command to run. - - `flagged: boolean` + - `env: map[string]` - A boolean indicating whether the content was flagged by any category. + Environment variables to set for the command. - - `model: string` + - `type: "exec"` - The moderation model that produced this result. + The type of the local shell action. Always `exec`. - - `type: "moderation_result"` + - `"exec"` - The object type, which was always `moderation_result` for successful moderation results. + - `timeout_ms: optional number` - - `"moderation_result"` + Optional timeout in milliseconds for the command. - - `Error object { code, message, type }` + - `user: optional string` - An error produced while attempting moderation for the response input or output. + Optional user to run the command as. - - `code: string` + - `working_directory: optional string` - The error code. + Optional working directory to run the command in. - - `message: string` + - `call_id: string` - The error message. + The unique ID of the local shell tool call generated by the model. - - `type: "error"` + - `status: "in_progress" or "completed" or "incomplete"` - The object type, which was always `error` for moderation failures. + The status of the local shell call. - - `"error"` + - `"in_progress"` - - `previous_response_id: optional string` + - `"completed"` - The unique ID of the previous response to the model. Use this to - create multi-turn conversations. Learn more about - [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + - `"incomplete"` - - `prompt: optional BetaResponsePrompt` + - `type: "local_shell_call"` - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + The type of the local shell call. Always `local_shell_call`. - - `id: string` + - `"local_shell_call"` - The unique identifier of the prompt template to use. + - `agent: optional object { agent_name }` - - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` + The agent that produced this item. - 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. + - `agent_name: string` - - `string` + The canonical name of the agent that produced this item. - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `LocalShellCallOutput object { id, output, type, 2 more }` - A text input to the model. + The output of a local shell tool call. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `id: string` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The unique ID of the local shell tool call generated by the model. - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `output: string` - A file input to the model. + A JSON string of the output of the local shell tool call. - - `version: optional string` + - `type: "local_shell_call_output"` - Optional version of the prompt template. + The type of the local shell tool call output. Always `local_shell_call_output`. - - `prompt_cache_key: optional string` + - `"local_shell_call_output"` - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + - `agent: optional object { agent_name }` - - `prompt_cache_options: optional object { mode, ttl }` + The agent that produced this item. - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + - `agent_name: string` - - `mode: "implicit" or "explicit"` + The canonical name of the agent that produced this item. - Whether implicit prompt-cache breakpoints were enabled. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"implicit"` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `"explicit"` + - `"in_progress"` - - `ttl: "30m"` + - `"completed"` - The minimum lifetime applied to each cache breakpoint. + - `"incomplete"` - - `"30m"` + - `ShellCall object { action, call_id, type, 5 more }` - - `prompt_cache_retention: optional "in_memory" or "24h"` + A tool representing a request to execute one or more shell commands. - Deprecated. Use `prompt_cache_options.ttl` instead. + - `action: object { commands, max_output_length, timeout_ms }` - 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](https://platform.openai.com/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 shell commands and limits that describe how to run the tool call. - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + - `commands: array of string` - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + Ordered shell commands for the execution environment to run. - - `"in_memory"` + - `max_output_length: optional number` - - `"24h"` + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - - `reasoning: optional object { context, effort, generate_summary, 2 more }` + - `timeout_ms: optional number` - **gpt-5 and o-series models only** + Maximum wall-clock time in milliseconds to allow the shell commands to run. - 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 shell tool call generated by the model. - Controls which reasoning items are rendered back to the model on later turns. - When returned on a response, this is the effective reasoning context mode - used for the response. + - `type: "shell_call"` - - `"auto"` + The type of the item. Always `shell_call`. - - `"current_turn"` + - `"shell_call"` - - `"all_turns"` + - `id: optional string` - - `effort: optional "none" or "minimal" or "low" or 4 more` + The unique ID of the shell tool call. Populated when this item is returned via API. - 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. + - `agent: optional object { agent_name }` - - `"none"` + The agent that produced this item. - - `"minimal"` + - `agent_name: string` - - `"low"` + The canonical name of the agent that produced this item. - - `"medium"` + - `caller: optional object { type } or object { caller_id, type }` - - `"high"` + The execution context that produced this tool call. - - `"xhigh"` + - `Direct object { type }` - - `"max"` + - `type: "direct"` - - `generate_summary: optional "auto" or "concise" or "detailed"` + The caller type. Always `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"` + The caller type. Always `program`. - Controls the reasoning execution mode for the request. + - `"program"` - When returned on a response, this is the effective execution mode. + - `environment: optional BetaLocalEnvironment or BetaContainerReference` - - `string` + The environment to execute the shell commands in. - - `"standard" or "pro"` + - `BetaLocalEnvironment object { type, skills }` - Controls the reasoning execution mode for the request. + - `BetaContainerReference object { container_id, type }` - When returned on a response, this is the effective execution mode. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"standard"` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `"pro"` + - `"in_progress"` - - `summary: optional "auto" or "concise" or "detailed"` + - `"completed"` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `"incomplete"` - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + - `ShellCallOutput object { call_id, output, type, 5 more }` - - `"auto"` + The streamed output items emitted by a shell tool call. - - `"concise"` + - `call_id: string` - - `"detailed"` + The unique ID of the shell tool call generated by the model. - - `safety_identifier: optional string` + - `output: array of BetaResponseFunctionShellCallOutputContent` - 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](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + Captured chunks of stdout and stderr output, along with their associated outcomes. - - `service_tier: optional "auto" or "default" or "flex" or 2 more` + - `outcome: object { type } or object { exit_code, type }` - Specifies the processing type used for serving the request. + The exit or timeout outcome associated with this shell 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](https://platform.openai.com/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'. + - `Timeout object { type }` - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + Indicates that the shell call exceeded its configured time limit. - - `"auto"` + - `type: "timeout"` - - `"default"` + The outcome type. Always `timeout`. - - `"flex"` + - `"timeout"` - - `"scale"` + - `Exit object { exit_code, type }` - - `"priority"` + Indicates that the shell commands finished and returned an exit code. - - `status: optional BetaResponseStatus` + - `exit_code: number` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + The exit code returned by the shell process. - - `"completed"` + - `type: "exit"` - - `"failed"` + The outcome type. Always `exit`. - - `"in_progress"` + - `"exit"` - - `"cancelled"` + - `stderr: string` - - `"queued"` + Captured stderr output for the shell call. - - `"incomplete"` + - `stdout: string` - - `text: optional BetaResponseTextConfig` + Captured stdout output for the shell call. - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + - `type: "shell_call_output"` - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + The type of the item. Always `shell_call_output`. - - `format: optional BetaResponseFormatTextConfig` + - `"shell_call_output"` - An object specifying the format that the model must output. + - `id: optional 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](https://platform.openai.com/docs/guides/structured-outputs). + The unique ID of the shell tool call output. Populated when this item is returned via API. - The default format is `{ "type": "text" }` with no additional options. + - `agent: optional object { agent_name }` - **Not recommended for gpt-4o and newer models:** + The agent that produced this item. - 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. + - `agent_name: string` - - `Text object { type }` + The canonical name of the agent that produced this item. - Default response format. Used to generate text responses. + - `caller: optional object { type } or object { caller_id, type }` - - `type: "text"` + The execution context that produced this tool call. - The type of response format being defined. Always `text`. + - `Direct object { type }` - - `"text"` + - `type: "direct"` - - `BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` + The caller type. Always `direct`. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `"direct"` - - `name: string` + - `Program object { caller_id, 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. + - `caller_id: string` - - `schema: map[unknown]` + The call ID of the program item that produced this 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/). + - `type: "program"` - - `type: "json_schema"` + The caller type. Always `program`. - The type of response format being defined. Always `json_schema`. + - `"program"` - - `"json_schema"` + - `max_output_length: optional number` - - `description: optional string` + The maximum number of UTF-8 characters captured for this shell call's combined output. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `strict: optional boolean` + The status of the shell call 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](https://platform.openai.com/docs/guides/structured-outputs). + - `"in_progress"` - - `JSONObject object { type }` + - `"completed"` - 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. + - `"incomplete"` - - `type: "json_object"` + - `ApplyPatchCall object { call_id, operation, status, 4 more }` - The type of response format being defined. Always `json_object`. + A tool call representing a request to create, delete, or update files using diff patches. - - `"json_object"` + - `call_id: string` - - `verbosity: optional "low" or "medium" or "high"` + The unique ID of the apply patch tool call generated by 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`. + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - - `"low"` + The specific create, delete, or update instruction for the apply_patch tool call. - - `"medium"` + - `CreateFile object { diff, path, type }` - - `"high"` + Instruction for creating a new file via the apply_patch tool. - - `top_logprobs: optional number` + - `diff: 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. + Unified diff content to apply when creating the file. - - `truncation: optional "auto" or "disabled"` + - `path: string` - The truncation strategy to use for the model response. + Path of the file to create relative to the workspace root. - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + - `type: "create_file"` - - `"auto"` + The operation type. Always `create_file`. - - `"disabled"` + - `"create_file"` - - `usage: optional BetaResponseUsage` + - `DeleteFile object { path, type }` - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + Instruction for deleting an existing file via the apply_patch tool. - - `input_tokens: number` + - `path: string` - The number of input tokens. + Path of the file to delete relative to the workspace root. - - `input_tokens_details: object { cache_write_tokens, cached_tokens }` + - `type: "delete_file"` - A detailed breakdown of the input tokens. + The operation type. Always `delete_file`. - - `cache_write_tokens: number` + - `"delete_file"` - The number of input tokens that were written to the cache. + - `UpdateFile object { diff, path, type }` - - `cached_tokens: number` + Instruction for updating an existing file via the apply_patch tool. - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + - `diff: string` - - `output_tokens: number` + Unified diff content to apply to the existing file. - The number of output tokens. + - `path: string` - - `output_tokens_details: object { reasoning_tokens }` + Path of the file to update relative to the workspace root. - A detailed breakdown of the output tokens. + - `type: "update_file"` - - `reasoning_tokens: number` + The operation type. Always `update_file`. - The number of reasoning tokens. + - `"update_file"` - - `total_tokens: number` + - `status: "in_progress" or "completed"` - The total number of tokens used. + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `user: optional string` + - `"in_progress"` - 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](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `"completed"` - - `sequence_number: number` + - `type: "apply_patch_call"` - The sequence number for this event. + The type of the item. Always `apply_patch_call`. - - `type: "response.completed"` + - `"apply_patch_call"` - The type of the event. Always `response.completed`. + - `id: optional string` - - `"response.completed"` + 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 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. - - `BetaResponseContentPartAddedEvent object { content_index, item_id, output_index, 4 more }` - - Emitted when a new content part is added. + - `caller: optional object { type } or object { caller_id, type }` - - `content_index: number` + The execution context that produced this tool call. - The index of the content part that was added. + - `Direct object { type }` - - `item_id: string` + - `type: "direct"` - The ID of the output item that the content part was added to. + The caller type. Always `direct`. - - `output_index: number` + - `"direct"` - The index of the output item that the content part was added to. + - `Program object { caller_id, type }` - - `part: BetaResponseOutputText or BetaResponseOutputRefusal or object { text, type }` + - `caller_id: string` - The content part that was added. + The call ID of the program item that produced this tool call. - - `BetaResponseOutputText object { annotations, text, type, logprobs }` + - `type: "program"` - A text output from the model. + The caller type. Always `program`. - - `BetaResponseOutputRefusal object { refusal, type }` + - `"program"` - A refusal from the model. + - `ApplyPatchCallOutput object { call_id, status, type, 4 more }` - - `ReasoningText object { text, type }` + The streamed output emitted by an apply patch tool call. - Reasoning text from the model. + - `call_id: string` - - `text: string` + The unique ID of the apply patch tool call generated by the model. - The reasoning text from the model. + - `status: "completed" or "failed"` - - `type: "reasoning_text"` + The status of the apply patch tool call output. One of `completed` or `failed`. - The type of the reasoning text. Always `reasoning_text`. + - `"completed"` - - `"reasoning_text"` + - `"failed"` - - `sequence_number: number` + - `type: "apply_patch_call_output"` - The sequence number of this event. + The type of the item. Always `apply_patch_call_output`. - - `type: "response.content_part.added"` + - `"apply_patch_call_output"` - The type of the event. Always `response.content_part.added`. + - `id: optional string` - - `"response.content_part.added"` + 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. - - `BetaResponseContentPartDoneEvent object { content_index, item_id, output_index, 4 more }` - - Emitted when a content part is done. - - - `content_index: number` - - The index of the content part that is done. - - - `item_id: string` - - The ID of the output item that the content part was added to. - - - `output_index: number` + - `caller: optional object { type } or object { caller_id, type }` - The index of the output item that the content part was added to. + The execution context that produced this tool call. - - `part: BetaResponseOutputText or BetaResponseOutputRefusal or object { text, type }` + - `Direct object { type }` - The content part that is done. + - `type: "direct"` - - `BetaResponseOutputText object { annotations, text, type, logprobs }` + The caller type. Always `direct`. - A text output from the model. + - `"direct"` - - `BetaResponseOutputRefusal object { refusal, type }` + - `Program object { caller_id, type }` - A refusal from the model. + - `caller_id: string` - - `ReasoningText object { text, type }` + The call ID of the program item that produced this tool call. - Reasoning text from the model. + - `type: "program"` - - `text: string` + The caller type. Always `program`. - The reasoning text from the model. + - `"program"` - - `type: "reasoning_text"` + - `output: optional string` - The type of the reasoning text. Always `reasoning_text`. + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - - `"reasoning_text"` + - `McpListTools object { id, server_label, tools, 3 more }` - - `sequence_number: number` + A list of tools available on an MCP server. - The sequence number of this event. + - `id: string` - - `type: "response.content_part.done"` + The unique ID of the list. - The type of the event. Always `response.content_part.done`. + - `server_label: string` - - `"response.content_part.done"` + The label of the MCP server. - - `agent: optional object { agent_name }` + - `tools: array of object { input_schema, name, annotations, description }` - The agent that owns this multi-agent streaming event. + The tools available on the server. - - `agent_name: string` + - `input_schema: unknown` - The canonical name of the agent that produced this item. + The JSON schema describing the tool's input. - - `BetaResponseCreatedEvent object { response, sequence_number, type, agent }` + - `name: string` - An event that is emitted when a response is created. + The name of the tool. - - `response: BetaResponse` + - `annotations: optional unknown` - The response that was created. + Additional annotations about the tool. - - `sequence_number: number` + - `description: optional string` - The sequence number for this event. + The description of the tool. - - `type: "response.created"` + - `type: "mcp_list_tools"` - The type of the event. Always `response.created`. + The type of the item. Always `mcp_list_tools`. - - `"response.created"` + - `"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. - - `BetaResponseErrorEvent object { code, message, param, 3 more }` + - `error: optional string` - Emitted when an error occurs. + Error message if the server could not list tools. - - `code: string` + - `McpApprovalRequest object { id, arguments, name, 3 more }` - The error code. + A request for human approval of a tool invocation. - - `message: string` + - `id: string` - The error message. + The unique ID of the approval request. - - `param: string` + - `arguments: string` - The error parameter. + A JSON string of arguments for the tool. - - `sequence_number: number` + - `name: string` - The sequence number of this event. + The name of the tool to run. - - `type: "error"` + - `server_label: string` - The type of the event. Always `error`. + The label of the MCP server making the request. - - `"error"` + - `type: "mcp_approval_request"` + + The type of the item. Always `mcp_approval_request`. + + - `"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. - - `BetaResponseFileSearchCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` + - `McpApprovalResponse object { approval_request_id, approve, type, 3 more }` - Emitted when a file search call is completed (results found). + A response to an MCP approval request. - - `item_id: string` + - `approval_request_id: string` - The ID of the output item that the file search call is initiated. + The ID of the approval request being answered. - - `output_index: number` + - `approve: boolean` - The index of the output item that the file search call is initiated. + 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.file_search_call.completed"` + - `"mcp_approval_response"` - The type of the event. Always `response.file_search_call.completed`. + - `id: optional string` - - `"response.file_search_call.completed"` + 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. - - `BetaResponseFileSearchCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` + - `reason: optional string` - Emitted when a file search call is initiated. + Optional reason for the decision. - - `item_id: string` + - `McpCall object { id, arguments, name, 7 more }` - The ID of the output item that the file search call is initiated. + An invocation of a tool on an MCP server. - - `output_index: number` + - `id: string` - The index of the output item that the file search call is initiated. + The unique ID of the tool call. - - `sequence_number: number` + - `arguments: string` - The sequence number of this event. + A JSON string of the arguments passed to the tool. - - `type: "response.file_search_call.in_progress"` + - `name: string` - The type of the event. Always `response.file_search_call.in_progress`. + The name of the tool that was run. - - `"response.file_search_call.in_progress"` + - `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 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 }` + - `approval_request_id: optional string` - Emitted when a file search is currently searching. + 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. - - `item_id: string` + - `error: optional string` - The ID of the output item that the file search call is initiated. + The error from the tool call, if any. - - `output_index: number` + - `output: optional string` - The index of the output item that the file search call is searching. + The output from the tool call. - - `sequence_number: number` + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - The sequence number of this event. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `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"` + - `"incomplete"` - - `agent: optional object { agent_name }` + - `"calling"` - The agent that owns this multi-agent streaming event. + - `"failed"` - - `agent_name: string` + - `CustomToolCallOutput object { call_id, output, type, 3 more }` - The canonical name of the agent that produced this item. + The output of a custom tool call from your code, being sent back to the model. - - `BetaResponseFunctionCallArgumentsDeltaEvent object { delta, item_id, output_index, 3 more }` + - `call_id: string` - Emitted when there is a partial function-call arguments delta. + The call ID, used to map this custom tool call output to a custom tool call. - - `delta: string` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - The function-call arguments delta that is added. + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `item_id: string` + - `StringOutput = string` - The ID of the output item that the function-call arguments delta is added to. + A string of the output of the custom tool call. - - `output_index: number` + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - The index of the output item that the function-call arguments delta is added to. + Text, image, or file output of the custom tool call. - - `sequence_number: number` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - The sequence number of this event. + A text input to the model. - - `type: "response.function_call_arguments.delta"` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - The type of the event. Always `response.function_call_arguments.delta`. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `"response.function_call_arguments.delta"` + - `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 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. - - `BetaResponseFunctionCallArgumentsDoneEvent object { arguments, item_id, name, 4 more }` - - Emitted when function-call arguments are finalized. - - - `arguments: string` + - `caller: optional object { type } or object { caller_id, type }` - The function-call arguments. + The execution context that produced this tool call. - - `item_id: string` + - `Direct object { type }` - The ID of the item. + - `type: "direct"` - - `name: string` + The caller type. Always `direct`. - The name of the function that was called. + - `"direct"` - - `output_index: number` + - `Program object { caller_id, type }` - The index of the output item. + - `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.function_call_arguments.done"` + The caller type. Always `program`. - - `"response.function_call_arguments.done"` + - `"program"` - - `agent: optional object { agent_name }` + - `CustomToolCall object { call_id, input, name, 5 more }` - The agent that owns this multi-agent streaming event. + A call to a custom tool created by the model. - - `agent_name: string` + - `call_id: string` - The canonical name of the agent that produced this item. + An identifier used to map this custom tool call to a tool call output. - - `BetaResponseInProgressEvent object { response, sequence_number, type, agent }` + - `input: string` - Emitted when the response is in progress. + The input for the custom tool call generated by the model. - - `response: BetaResponse` + - `name: string` - The response that is in progress. + The name of the custom tool being called. - - `sequence_number: number` + - `type: "custom_tool_call"` - The sequence number of this event. + The type of the custom tool call. Always `custom_tool_call`. - - `type: "response.in_progress"` + - `"custom_tool_call"` - The type of the event. Always `response.in_progress`. + - `id: optional string` - - `"response.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. - - `BetaResponseFailedEvent object { response, sequence_number, type, agent }` + - `caller: optional object { type } or object { caller_id, type }` - An event that is emitted when a response fails. + The execution context that produced this tool call. - - `response: BetaResponse` + - `Direct object { type }` - The response that failed. + - `type: "direct"` - - `sequence_number: number` + - `"direct"` - The sequence number of this event. + - `Program object { caller_id, type }` - - `type: "response.failed"` + - `caller_id: string` - The type of the event. Always `response.failed`. + The call ID of the program item that produced this tool call. - - `"response.failed"` + - `type: "program"` - - `agent: optional object { agent_name }` + - `"program"` - The agent that owns this multi-agent streaming event. + - `namespace: optional string` - - `agent_name: string` + The namespace of the custom tool being called. - The canonical name of the agent that produced this item. + - `CompactionTrigger object { type, agent }` - - `BetaResponseIncompleteEvent object { response, sequence_number, type, agent }` + Compacts the current context. Must be the final input item. - An event that is emitted when a response finishes as incomplete. + - `type: "compaction_trigger"` - - `response: BetaResponse` + The type of the item. Always `compaction_trigger`. - The response that was incomplete. + - `"compaction_trigger"` - - `sequence_number: number` + - `agent: optional object { agent_name }` - The sequence number of this event. + The agent that produced this item. - - `type: "response.incomplete"` + - `agent_name: string` - The type of the event. Always `response.incomplete`. + The canonical name of the agent that produced this item. - - `"response.incomplete"` + - `ItemReference object { id, agent, type }` - - `agent: optional object { agent_name }` + An internal identifier for an item to reference. - The agent that owns this multi-agent streaming event. + - `id: string` - - `agent_name: string` + The ID of the item to reference. - The canonical name of the agent that produced this item. + - `agent: optional object { agent_name }` - - `BetaResponseOutputItemAddedEvent object { item, output_index, sequence_number, 2 more }` + The agent that produced this item. - Emitted when a new output item is added. + - `agent_name: string` - - `item: BetaResponseOutputItem` + The canonical name of the agent that produced this item. - The output item that was added. + - `type: optional "item_reference"` - - `BetaResponseOutputMessage object { id, content, role, 4 more }` + The type of item to reference. Always `item_reference`. - An output message from the model. + - `"item_reference"` - - `FileSearchCall object { id, queries, status, 3 more }` + - `Program object { id, call_id, code, 3 more }` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `id: string` - - `FunctionCall object { arguments, call_id, name, 6 more }` + The unique ID of this program item. - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `call_id: string` - - `FunctionCallOutput object { id, call_id, output, 5 more }` + The stable call ID of the program item. - - `AgentMessage object { id, author, content, 3 more }` + - `code: string` - - `MultiAgentCall object { id, action, arguments, 3 more }` + The JavaScript source executed by programmatic tool calling. - - `MultiAgentCallOutput object { id, action, call_id, 3 more }` + - `fingerprint: string` - - `WebSearchCall object { id, action, status, 2 more }` + Opaque program replay fingerprint that must be round-tripped. - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `type: "program"` - - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` + The item type. Always `program`. - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + - `"program"` - - `ComputerCallOutput object { id, call_id, output, 5 more }` + - `agent: optional object { agent_name }` - - `Reasoning object { id, summary, type, 4 more }` + The agent that produced this 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](https://platform.openai.com/docs/guides/conversation-state). + - `agent_name: string` - - `Program object { id, call_id, code, 3 more }` + The canonical name of the agent that produced this item. - `ProgramOutput object { id, call_id, result, 3 more }` - - `ToolSearchCall object { id, arguments, call_id, 5 more }` + - `id: string` - - `ToolSearchOutput object { id, call_id, execution, 5 more }` + The unique ID of this program output item. - - `AdditionalTools object { id, role, tools, 2 more }` + - `call_id: string` - - `Compaction object { id, encrypted_content, type, 2 more }` + The call ID of the program item. - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `result: string` - - `ImageGenerationCall object { id, result, status, 2 more }` + The result produced by the program item. - An image generation request made by the model. + - `status: "completed" or "incomplete"` - - `CodeInterpreterCall object { id, code, container_id, 4 more }` + The terminal status of the program output. - A tool call to run code. + - `"completed"` - - `LocalShellCall object { id, action, call_id, 3 more }` + - `"incomplete"` - A tool call to run a command on the local shell. + - `type: "program_output"` - - `LocalShellCallOutput object { id, output, type, 2 more }` + The item type. Always `program_output`. - The output of a local shell tool call. + - `"program_output"` - - `ShellCall object { id, action, call_id, 6 more }` + - `agent: optional object { agent_name }` - A tool call that executes one or more shell commands in a managed environment. + The agent that produced this item. - - `ShellCallOutput object { id, call_id, max_output_length, 6 more }` + - `agent_name: string` - The output of a shell tool call that was emitted. + The canonical name of the agent that produced this item. - - `ApplyPatchCall object { id, call_id, operation, 5 more }` + - `metadata: map[string]` - A tool call that applies file diffs by creating, deleting, or updating files. + 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. - - `ApplyPatchCallOutput object { id, call_id, status, 5 more }` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The output emitted by an apply patch tool call. + - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` - - `McpCall object { id, arguments, name, 7 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. - An invocation of a tool on an MCP server. + - `"gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more` - - `McpListTools object { id, server_label, tools, 3 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 list of tools available on an MCP server. + - `"gpt-5.6-sol"` - - `McpApprovalRequest object { id, arguments, name, 3 more }` + - `"gpt-5.6-terra"` - A request for human approval of a tool invocation. + - `"gpt-5.6-luna"` - - `McpApprovalResponse object { id, approval_request_id, approve, 3 more }` + - `"gpt-5.4"` - A response to an MCP approval request. + - `"gpt-5.4-mini"` - - `CustomToolCall object { call_id, input, name, 5 more }` + - `"gpt-5.4-nano"` - A call to a custom tool created by the model. + - `"gpt-5.4-mini-2026-03-17"` - - `CustomToolCallOutput object { id, call_id, output, 5 more }` + - `"gpt-5.4-nano-2026-03-17"` - - `output_index: number` + - `"gpt-5.3-chat-latest"` - The index of the output item that was added. + - `"gpt-5.2"` - - `sequence_number: number` + - `"gpt-5.2-2025-12-11"` - The sequence number of this event. + - `"gpt-5.2-chat-latest"` - - `type: "response.output_item.added"` + - `"gpt-5.2-pro"` - The type of the event. Always `response.output_item.added`. + - `"gpt-5.2-pro-2025-12-11"` - - `"response.output_item.added"` + - `"gpt-5.1"` - - `agent: optional object { agent_name }` + - `"gpt-5.1-2025-11-13"` - The agent that owns this multi-agent streaming event. + - `"gpt-5.1-codex"` - - `agent_name: string` + - `"gpt-5.1-mini"` - The canonical name of the agent that produced this item. + - `"gpt-5.1-chat-latest"` - - `BetaResponseOutputItemDoneEvent object { item, output_index, sequence_number, 2 more }` + - `"gpt-5"` - Emitted when an output item is marked done. + - `"gpt-5-mini"` - - `item: BetaResponseOutputItem` + - `"gpt-5-nano"` - The output item that was marked done. + - `"gpt-5-2025-08-07"` - - `output_index: number` + - `"gpt-5-mini-2025-08-07"` - The index of the output item that was marked done. + - `"gpt-5-nano-2025-08-07"` - - `sequence_number: number` + - `"gpt-5-chat-latest"` - The sequence number of this event. + - `"gpt-4.1"` - - `type: "response.output_item.done"` + - `"gpt-4.1-mini"` - The type of the event. Always `response.output_item.done`. + - `"gpt-4.1-nano"` - - `"response.output_item.done"` + - `"gpt-4.1-2025-04-14"` - - `agent: optional object { agent_name }` + - `"gpt-4.1-mini-2025-04-14"` - The agent that owns this multi-agent streaming event. + - `"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"` - - `BetaResponseReasoningSummaryPartAddedEvent object { item_id, output_index, part, 4 more }` + - `"o3"` - Emitted when a new reasoning summary part is added. + - `"o3-2025-04-16"` - - `item_id: string` + - `"o3-mini"` - The ID of the item this summary part is associated with. + - `"o3-mini-2025-01-31"` - - `output_index: number` + - `"o1"` - The index of the output item this summary part is associated with. + - `"o1-2024-12-17"` - - `part: object { text, type }` + - `"o1-preview"` - The summary part that was added. + - `"o1-preview-2024-09-12"` - - `text: string` + - `"o1-mini"` - The text of the summary part. + - `"o1-mini-2024-09-12"` - - `type: "summary_text"` + - `"gpt-4o"` - The type of the summary part. Always `summary_text`. + - `"gpt-4o-2024-11-20"` - - `"summary_text"` + - `"gpt-4o-2024-08-06"` - - `sequence_number: number` + - `"gpt-4o-2024-05-13"` - The sequence number of this event. + - `"gpt-4o-audio-preview"` - - `summary_index: number` + - `"gpt-4o-audio-preview-2024-10-01"` - The index of the summary part within the reasoning summary. + - `"gpt-4o-audio-preview-2024-12-17"` - - `type: "response.reasoning_summary_part.added"` + - `"gpt-4o-audio-preview-2025-06-03"` - The type of the event. Always `response.reasoning_summary_part.added`. + - `"gpt-4o-mini-audio-preview"` + + - `"gpt-4o-mini-audio-preview-2024-12-17"` - - `"response.reasoning_summary_part.added"` + - `"gpt-4o-search-preview"` - - `agent: optional object { agent_name }` + - `"gpt-4o-mini-search-preview"` - The agent that owns this multi-agent streaming event. + - `"gpt-4o-search-preview-2025-03-11"` - - `agent_name: string` + - `"gpt-4o-mini-search-preview-2025-03-11"` - The canonical name of the agent that produced this item. + - `"chatgpt-4o-latest"` - - `BetaResponseReasoningSummaryPartDoneEvent object { item_id, output_index, part, 5 more }` + - `"codex-mini-latest"` - Emitted when a reasoning summary part is completed. + - `"gpt-4o-mini"` - - `item_id: string` + - `"gpt-4o-mini-2024-07-18"` - The ID of the item this summary part is associated with. + - `"gpt-4-turbo"` - - `output_index: number` + - `"gpt-4-turbo-2024-04-09"` - The index of the output item this summary part is associated with. + - `"gpt-4-0125-preview"` - - `part: object { text, type }` + - `"gpt-4-turbo-preview"` - The completed summary part. + - `"gpt-4-1106-preview"` - - `text: string` + - `"gpt-4-vision-preview"` - The text of the summary part. + - `"gpt-4"` - - `type: "summary_text"` + - `"gpt-4-0314"` - The type of the summary part. Always `summary_text`. + - `"gpt-4-0613"` - - `"summary_text"` + - `"gpt-4-32k"` - - `sequence_number: number` + - `"gpt-4-32k-0314"` - The sequence number of this event. + - `"gpt-4-32k-0613"` - - `summary_index: number` + - `"gpt-3.5-turbo"` - The index of the summary part within the reasoning summary. + - `"gpt-3.5-turbo-16k"` - - `type: "response.reasoning_summary_part.done"` + - `"gpt-3.5-turbo-0301"` - The type of the event. Always `response.reasoning_summary_part.done`. + - `"gpt-3.5-turbo-0613"` - - `"response.reasoning_summary_part.done"` + - `"gpt-3.5-turbo-1106"` - - `agent: optional object { agent_name }` + - `"gpt-3.5-turbo-0125"` - The agent that owns this multi-agent streaming event. + - `"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 "incomplete"` + - `"o3-pro"` - The completion status of the summary part. Omitted when the part completed - normally and set to `incomplete` when generation was interrupted. + - `"o3-pro-2025-06-10"` - - `"incomplete"` + - `"o3-deep-research"` - - `BetaResponseReasoningSummaryTextDeltaEvent object { delta, item_id, output_index, 4 more }` + - `"o3-deep-research-2025-06-26"` - Emitted when a delta is added to a reasoning summary text. + - `"o4-mini-deep-research"` - - `delta: string` + - `"o4-mini-deep-research-2025-06-26"` - The text delta that was added to the summary. + - `"computer-use-preview"` - - `item_id: string` + - `"computer-use-preview-2025-03-11"` - The ID of the item this summary text delta is associated with. + - `"gpt-5-codex"` - - `output_index: number` + - `"gpt-5-pro"` - The index of the output item this summary text delta is associated with. + - `"gpt-5-pro-2025-10-06"` - - `sequence_number: number` + - `"gpt-5.1-codex-max"` - The sequence number of this event. + - `string` - - `summary_index: number` + - `object: "response"` - The index of the summary part within the reasoning summary. + The object type of this resource - always set to `response`. - - `type: "response.reasoning_summary_text.delta"` + - `"response"` - The type of the event. Always `response.reasoning_summary_text.delta`. + - `output: array of BetaResponseOutputItem` - - `"response.reasoning_summary_text.delta"` + 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 }` - - `BetaResponseReasoningSummaryTextDoneEvent object { item_id, output_index, sequence_number, 4 more }` + The results of a file search tool call. See the + [file search guide](/docs/guides/tools-file-search) for more information. - Emitted when a reasoning summary text is completed. + - `id: string` - - `item_id: string` + The unique ID of the file search tool call. - The ID of the item this summary text is associated with. + - `queries: array of string` - - `output_index: number` + The queries used to search for files. - The index of the output item this summary text is associated with. + - `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"` - - `summary_index: number` + - `"searching"` - The index of the summary part within the reasoning summary. + - `"completed"` - - `text: string` + - `"incomplete"` - The full text of the completed reasoning summary. + - `"failed"` - - `type: "response.reasoning_summary_text.done"` + - `type: "file_search_call"` - The type of the event. Always `response.reasoning_summary_text.done`. + The type of the file search tool call. Always `file_search_call`. - - `"response.reasoning_summary_text.done"` + - `"file_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. - - `BetaResponseReasoningTextDeltaEvent object { content_index, delta, item_id, 4 more }` + - `results: optional array of object { attributes, file_id, filename, 2 more }` - Emitted when a delta is added to a reasoning text. + The results of the file search tool call. - - `content_index: number` + - `attributes: optional map[string or number or boolean]` - The index of the reasoning content part this delta is 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. Keys are strings + with a maximum length of 64 characters. Values are strings with a maximum + length of 512 characters, booleans, or numbers. - - `delta: string` + - `string` - The text delta that was added to the reasoning content. + - `number` - - `item_id: string` + - `boolean` - The ID of the item this reasoning text delta is associated with. + - `file_id: optional string` - - `output_index: number` + The unique ID of the file. - The index of the output item this reasoning text delta is associated with. + - `filename: optional string` - - `sequence_number: number` + The name of the file. - The sequence number of this event. + - `score: optional number` - - `type: "response.reasoning_text.delta"` + The relevance score of the file - a value between 0 and 1. - The type of the event. Always `response.reasoning_text.delta`. + - `text: optional string` - - `"response.reasoning_text.delta"` + The text that was retrieved from the file. - - `agent: optional object { agent_name }` + - `FunctionCall object { arguments, call_id, name, 6 more }` - The agent that owns this multi-agent streaming event. + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. - - `agent_name: string` + - `arguments: string` - The canonical name of the agent that produced this item. + A JSON string of the arguments to pass to the function. - - `BetaResponseReasoningTextDoneEvent object { content_index, item_id, output_index, 4 more }` + - `call_id: string` - Emitted when a reasoning text is completed. + The unique ID of the function tool call generated by the model. - - `content_index: number` + - `name: string` - The index of the reasoning content part. + The name of the function to run. - - `item_id: string` + - `type: "function_call"` - The ID of the item this reasoning text is associated with. + The type of the function tool call. Always `function_call`. - - `output_index: number` + - `"function_call"` - The index of the output item this reasoning text is associated with. + - `id: optional string` - - `sequence_number: number` + The unique ID of the function tool call. - The sequence number of this event. + - `agent: optional object { agent_name }` - - `text: string` + The agent that produced this item. - The full text of the completed reasoning content. + - `agent_name: string` - - `type: "response.reasoning_text.done"` + The canonical name of the agent that produced this item. - The type of the event. Always `response.reasoning_text.done`. + - `caller: optional object { type } or object { caller_id, type }` - - `"response.reasoning_text.done"` + The execution context that produced this tool call. - - `agent: optional object { agent_name }` + - `Direct object { type }` - The agent that owns this multi-agent streaming event. + - `type: "direct"` - - `agent_name: string` + - `"direct"` - The canonical name of the agent that produced this item. + - `Program object { caller_id, type }` - - `BetaResponseRefusalDeltaEvent object { content_index, delta, item_id, 4 more }` + - `caller_id: string` - Emitted when there is a partial refusal text. + The call ID of the program item that produced this tool call. - - `content_index: number` + - `type: "program"` - The index of the content part that the refusal text is added to. + - `"program"` - - `delta: string` + - `namespace: optional string` - The refusal text that is added. + The namespace of the function to run. - - `item_id: string` + - `status: optional "in_progress" or "completed" or "incomplete"` - The ID of the output item that the refusal text is added to. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `output_index: number` + - `"in_progress"` - The index of the output item that the refusal text is added to. + - `"completed"` - - `sequence_number: number` + - `"incomplete"` - The sequence number of this event. + - `FunctionCallOutput object { id, call_id, output, 5 more }` - - `type: "response.refusal.delta"` + - `id: string` - The type of the event. Always `response.refusal.delta`. + The unique ID of the function call tool output. - - `"response.refusal.delta"` + - `call_id: string` - - `agent: optional object { agent_name }` + The unique ID of the function tool call generated by the model. - The agent that owns this multi-agent streaming event. + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `agent_name: string` + The output from the function call generated by your code. + Can be a string or an list of output content. - The canonical name of the agent that produced this item. + - `StringOutput = string` - - `BetaResponseRefusalDoneEvent object { content_index, item_id, output_index, 4 more }` + A string of the output of the function call. - Emitted when refusal text is finalized. + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `content_index: number` + Text, image, or file output of the function call. - The index of the content part that the refusal text is finalized. + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `item_id: string` + A text input to the model. - The ID of the output item that the refusal text is finalized. + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `output_index: number` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - The index of the output item that the refusal text is finalized. + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `refusal: string` + A file input to the model. - The refusal text that is finalized. + - `status: "in_progress" or "completed" or "incomplete"` - - `sequence_number: number` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The sequence number of this event. + - `"in_progress"` - - `type: "response.refusal.done"` + - `"completed"` - The type of the event. Always `response.refusal.done`. + - `"incomplete"` - - `"response.refusal.done"` + - `type: "function_call_output"` + + The type of the function tool call output. Always `function_call_output`. + + - `"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. - - `BetaResponseTextDeltaEvent object { content_index, delta, item_id, 5 more }` + - `caller: optional object { type } or object { caller_id, type }` - Emitted when there is an additional text delta. + The execution context that produced this tool call. - - `content_index: number` + - `Direct object { type }` - The index of the content part that the text delta was added to. + - `type: "direct"` - - `delta: string` + The caller type. Always `direct`. - The text delta that was added. + - `"direct"` - - `item_id: string` + - `Program object { caller_id, type }` - The ID of the output item that the text delta was added to. + - `caller_id: string` - - `logprobs: array of object { token, logprob, top_logprobs }` + The call ID of the program item that produced this tool call. - The log probabilities of the tokens in the delta. + - `type: "program"` - - `token: string` + The caller type. Always `program`. - A possible text token. + - `"program"` - - `logprob: number` + - `created_by: optional string` - The log probability of this token. + The identifier of the actor that created the item. - - `top_logprobs: optional array of object { token, logprob }` + - `AgentMessage object { id, author, content, 3 more }` - The log probabilities of up to 20 of the most likely tokens. + - `id: string` - - `token: optional string` + The unique ID of the agent message. - A possible text token. + - `author: string` - - `logprob: optional number` + The sending agent identity. - The log probability of this token. + - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` - - `output_index: number` + Encrypted content sent between agents. - The index of the output item that the text delta was added to. + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `sequence_number: number` + A text input to the model. - The sequence number for this event. + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - - `type: "response.output_text.delta"` + A text output from the model. - The type of the event. Always `response.output_text.delta`. + - `Text object { text, type }` - - `"response.output_text.delta"` + A text content. - - `agent: optional object { agent_name }` + - `text: string` - The agent that owns this multi-agent streaming event. + - `type: "text"` - - `agent_name: string` + - `"text"` - The canonical name of the agent that produced this item. + - `SummaryText object { text, type }` - - `BetaResponseTextDoneEvent object { content_index, item_id, logprobs, 5 more }` + A summary text from the model. - Emitted when text content is finalized. + - `text: string` - - `content_index: number` + A summary of the reasoning output from the model so far. - The index of the content part that the text content is finalized. + - `type: "summary_text"` - - `item_id: string` + The type of the object. Always `summary_text`. - The ID of the output item that the text content is finalized. + - `"summary_text"` - - `logprobs: array of object { token, logprob, top_logprobs }` + - `ReasoningText object { text, type }` - The log probabilities of the tokens in the delta. + Reasoning text from the model. - - `token: string` + - `text: string` - A possible text token. + The reasoning text from the model. - - `logprob: number` + - `type: "reasoning_text"` - The log probability of this token. + The type of the reasoning text. Always `reasoning_text`. - - `top_logprobs: optional array of object { token, logprob }` + - `"reasoning_text"` - The log probabilities of up to 20 of the most likely tokens. + - `BetaResponseOutputRefusal object { refusal, type }` - - `token: optional string` + A refusal from the model. - A possible text token. + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `logprob: optional number` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - The log probability of this token. + - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` - - `output_index: number` + A screenshot of a computer. - The index of the output item that the text content is finalized. + - `detail: "low" or "high" or "auto" or "original"` - - `sequence_number: 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 sequence number for this event. + - `"low"` - - `text: string` + - `"high"` - The text content that is finalized. + - `"auto"` - - `type: "response.output_text.done"` + - `"original"` - The type of the event. Always `response.output_text.done`. + - `file_id: string` - - `"response.output_text.done"` + The identifier of an uploaded file that contains the screenshot. - - `agent: optional object { agent_name }` + - `image_url: string` - The agent that owns this multi-agent streaming event. + The URL of the screenshot image. - - `agent_name: string` + - `type: "computer_screenshot"` - The canonical name of the agent that produced this item. + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `BetaResponseWebSearchCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` + - `"computer_screenshot"` - Emitted when a web search call is completed. + - `prompt_cache_breakpoint: optional object { mode }` - - `item_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. - Unique ID for the output item associated with the web search call. + - `mode: "explicit"` - - `output_index: number` + The breakpoint mode. Always `explicit`. - The index of the output item that the web search call is associated with. + - `"explicit"` - - `sequence_number: number` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - The sequence number of the web search call being processed. + A file input to the model. - - `type: "response.web_search_call.completed"` + - `EncryptedContent object { encrypted_content, type }` - The type of the event. Always `response.web_search_call.completed`. + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `"response.web_search_call.completed"` + - `encrypted_content: string` - - `agent: optional object { agent_name }` + Opaque encrypted content. - The agent that owns this multi-agent streaming event. + - `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"` - - `BetaResponseWebSearchCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` + - `recipient: string` - Emitted when a web search call is initiated. + The destination agent identity. - - `item_id: string` + - `type: "agent_message"` - Unique ID for the output item associated with the web search call. + The type of the item. Always `agent_message`. - - `output_index: number` + - `"agent_message"` - 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.in_progress"` + The canonical name of the agent that produced this item. - The type of the event. Always `response.web_search_call.in_progress`. + - `MultiAgentCall object { id, action, arguments, 3 more }` - - `"response.web_search_call.in_progress"` + - `id: string` - - `agent: optional object { agent_name }` + The unique ID of the multi-agent call item. - The agent that owns this multi-agent streaming event. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `agent_name: string` + The multi-agent action to execute. - The canonical name of the agent that produced this item. + - `"spawn_agent"` - - `BetaResponseWebSearchCallSearchingEvent object { item_id, output_index, sequence_number, 2 more }` + - `"interrupt_agent"` - Emitted when a web search call is executing. + - `"list_agents"` - - `item_id: string` + - `"send_message"` - Unique ID for the output item associated with the web search call. + - `"followup_task"` - - `output_index: number` + - `"wait_agent"` - The index of the output item that the web search call is associated with. + - `arguments: string` - - `sequence_number: number` + The JSON string of arguments generated for the action. - The sequence number of the web search call being processed. + - `call_id: string` - - `type: "response.web_search_call.searching"` + The unique ID linking this call to its output. - The type of the event. Always `response.web_search_call.searching`. + - `type: "multi_agent_call"` - - `"response.web_search_call.searching"` + The type of the multi-agent call. Always `multi_agent_call`. + + - `"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. - - `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. + - `MultiAgentCallOutput object { id, action, call_id, 3 more }` - - `item_id: string` + - `id: string` - The unique identifier of the image generation item being processed. + The unique ID of the multi-agent call output item. - - `output_index: number` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - The index of the output item in the response's output array. + The multi-agent action that produced this result. - - `sequence_number: number` + - `"spawn_agent"` - The sequence number of this event. + - `"interrupt_agent"` - - `type: "response.image_generation_call.completed"` + - `"list_agents"` - The type of the event. Always 'response.image_generation_call.completed'. + - `"send_message"` - - `"response.image_generation_call.completed"` + - `"followup_task"` - - `agent: optional object { agent_name }` + - `"wait_agent"` - The agent that owns this multi-agent streaming event. + - `call_id: string` - - `agent_name: string` + The unique ID of the multi-agent call. - The canonical name of the agent that produced this item. + - `output: array of BetaResponseOutputText` - - `BetaResponseImageGenCallGeneratingEvent object { item_id, output_index, sequence_number, 2 more }` + Text output returned by the multi-agent action. - Emitted when an image generation tool call is actively generating an image (intermediate state). + - `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 }` - - `item_id: string` + The annotations of the text output. - The unique identifier of the image generation item being processed. + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - - `output_index: number` + - `text: string` - The index of the output item in the response's output array. + The text output from the model. - - `sequence_number: number` + - `type: "output_text"` - The sequence number of the image generation item being processed. + The type of the output text. Always `output_text`. - - `type: "response.image_generation_call.generating"` + - `type: "multi_agent_call_output"` - The type of the event. Always 'response.image_generation_call.generating'. + The type of the multi-agent result. Always `multi_agent_call_output`. - - `"response.image_generation_call.generating"` + - `"multi_agent_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. - - `BetaResponseImageGenCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` + - `WebSearchCall object { id, action, status, 2 more }` - Emitted when an image generation tool call is in progress. + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. - - `item_id: string` + - `id: string` - The unique identifier of the image generation item being processed. + The unique ID of the web search tool call. - - `output_index: number` + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - The index of the output item in the response's output array. + 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). - - `sequence_number: number` + - `Search object { type, queries, query, sources }` - The sequence number of the image generation item being processed. + Action type "search" - Performs a web search query. - - `type: "response.image_generation_call.in_progress"` + - `type: "search"` - The type of the event. Always 'response.image_generation_call.in_progress'. + The action type. - - `"response.image_generation_call.in_progress"` + - `"search"` - - `agent: optional object { agent_name }` + - `queries: optional array of string` - The agent that owns this multi-agent streaming event. + The search queries. - - `agent_name: string` + - `query: optional string` - The canonical name of the agent that produced this item. + The search query. - - `BetaResponseImageGenCallPartialImageEvent object { item_id, output_index, partial_image_b64, 4 more }` + - `sources: optional array of object { type, url }` - Emitted when a partial image is available during image generation streaming. + The sources used in the search. - - `item_id: string` + - `type: "url"` - The unique identifier of the image generation item being processed. + The type of source. Always `url`. - - `output_index: number` + - `"url"` - The index of the output item in the response's output array. + - `url: string` - - `partial_image_b64: string` + The URL of the source. - Base64-encoded partial image data, suitable for rendering as an image. + - `OpenPage object { type, url }` - - `partial_image_index: number` + Action type "open_page" - Opens a specific URL from search results. - 0-based index for the partial image (backend is 1-based, but this is 0-based for the user). + - `type: "open_page"` - - `sequence_number: number` + The action type. - The sequence number of the image generation item being processed. + - `"open_page"` - - `type: "response.image_generation_call.partial_image"` + - `url: optional string` - The type of the event. Always 'response.image_generation_call.partial_image'. + The URL opened by the model. - - `"response.image_generation_call.partial_image"` + - `FindInPage object { pattern, type, url }` - - `agent: optional object { agent_name }` + Action type "find_in_page": Searches for a pattern within a loaded page. - The agent that owns this multi-agent streaming event. + - `pattern: string` - - `agent_name: string` + The pattern or text to search for within the page. - The canonical name of the agent that produced this item. + - `type: "find_in_page"` - - `BetaResponseMcpCallArgumentsDeltaEvent object { delta, item_id, output_index, 3 more }` + The action type. - Emitted when there is a delta (partial update) to the arguments of an MCP tool call. + - `"find_in_page"` - - `delta: string` + - `url: string` - A JSON string containing the partial update to the arguments for the MCP tool call. + The URL of the page searched for the pattern. - - `item_id: string` + - `status: "in_progress" or "searching" or "completed" or "failed"` - The unique identifier of the MCP tool call item being processed. + The status of the web search tool call. - - `output_index: number` + - `"in_progress"` - The index of the output item in the response's output array. + - `"searching"` - - `sequence_number: number` + - `"completed"` - The sequence number of this event. + - `"failed"` - - `type: "response.mcp_call_arguments.delta"` + - `type: "web_search_call"` - The type of the event. Always 'response.mcp_call_arguments.delta'. + The type of the web search tool call. Always `web_search_call`. - - `"response.mcp_call_arguments.delta"` + - `"web_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. - - `BetaResponseMcpCallArgumentsDoneEvent object { arguments, item_id, output_index, 3 more }` - - Emitted when the arguments for an MCP tool call are finalized. - - - `arguments: string` + - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` - A JSON string containing the finalized arguments for the MCP tool call. + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - - `item_id: string` + - `id: string` - The unique identifier of the MCP tool call item being processed. + The unique ID of the computer call. - - `output_index: number` + - `call_id: string` - The index of the output item in the response's output array. + An identifier used when responding to the tool call with output. - - `sequence_number: number` + - `pending_safety_checks: array of object { id, code, message }` - The sequence number of this event. + The pending safety checks for the computer call. - - `type: "response.mcp_call_arguments.done"` + - `id: string` - The type of the event. Always 'response.mcp_call_arguments.done'. + The ID of the pending safety check. - - `"response.mcp_call_arguments.done"` + - `code: optional string` - - `agent: optional object { agent_name }` + The type of the pending safety check. - The agent that owns this multi-agent streaming event. + - `message: optional string` - - `agent_name: string` + Details about the pending safety check. - The canonical name of the agent that produced this item. + - `status: "in_progress" or "completed" or "incomplete"` - - `BetaResponseMcpCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Emitted when an MCP tool call has completed successfully. + - `"in_progress"` - - `item_id: string` + - `"completed"` - The ID of the MCP tool call item that completed. + - `"incomplete"` - - `output_index: number` + - `type: "computer_call"` - The index of the output item that completed. + The type of the computer call. Always `computer_call`. - - `sequence_number: number` + - `"computer_call"` - The sequence number of this event. + - `action: optional BetaComputerAction` - - `type: "response.mcp_call.completed"` + A click action. - The type of the event. Always 'response.mcp_call.completed'. + - `actions: optional BetaComputerActionList` - - `"response.mcp_call.completed"` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - `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. - - `BetaResponseMcpCallFailedEvent object { item_id, output_index, sequence_number, 2 more }` - - Emitted when an MCP tool call has failed. - - - `item_id: string` + - `ComputerCallOutput object { id, call_id, output, 5 more }` - The ID of the MCP tool call item that failed. + - `id: string` - - `output_index: number` + The unique ID of the computer call tool output. - The index of the output item that failed. + - `call_id: string` - - `sequence_number: number` + The ID of the computer tool call that produced the output. - The sequence number of this event. + - `output: BetaResponseComputerToolCallOutputScreenshot` - - `type: "response.mcp_call.failed"` + A computer screenshot image used with the computer use tool. - The type of the event. Always 'response.mcp_call.failed'. + - `status: "completed" or "incomplete" or "failed" or "in_progress"` - - `"response.mcp_call.failed"` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `agent: optional object { agent_name }` + - `"completed"` - The agent that owns this multi-agent streaming event. + - `"incomplete"` - - `agent_name: string` + - `"failed"` - The canonical name of the agent that produced this item. + - `"in_progress"` - - `BetaResponseMcpCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` + - `type: "computer_call_output"` - Emitted when an MCP tool call is in progress. + The type of the computer tool call output. Always `computer_call_output`. - - `item_id: string` + - `"computer_call_output"` - The unique identifier of the MCP tool call item being processed. + - `acknowledged_safety_checks: optional array of object { id, code, message }` - - `output_index: number` + The safety checks reported by the API that have been acknowledged by the + developer. - The index of the output item in the response's output array. + - `id: string` - - `sequence_number: number` + The ID of the pending safety check. - The sequence number of this event. + - `code: optional string` - - `type: "response.mcp_call.in_progress"` + The type of the pending safety check. - The type of the event. Always 'response.mcp_call.in_progress'. + - `message: optional string` - - `"response.mcp_call.in_progress"` + Details about the pending safety check. - `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. - - `BetaResponseMcpListToolsCompletedEvent object { item_id, output_index, sequence_number, 2 more }` + - `created_by: optional string` - Emitted when the list of available MCP tools has been successfully retrieved. + The identifier of the actor that created the item. - - `item_id: string` + - `Reasoning object { id, summary, type, 4 more }` - The ID of the MCP tool call item that produced this output. + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](/docs/guides/conversation-state). - - `output_index: number` + - `id: string` - The index of the output item that was processed. + The unique identifier of the reasoning content. - - `sequence_number: number` + - `summary: array of object { text, type }` - The sequence number of this event. + Reasoning summary content. - - `type: "response.mcp_list_tools.completed"` + - `text: string` - The type of the event. Always 'response.mcp_list_tools.completed'. + A summary of the reasoning output from the model so far. - - `"response.mcp_list_tools.completed"` + - `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 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. - - `BetaResponseMcpListToolsFailedEvent object { item_id, output_index, sequence_number, 2 more }` + - `content: optional array of object { text, type }` - Emitted when the attempt to list available MCP tools has failed. + Reasoning text content. - - `item_id: string` + - `text: string` - The ID of the MCP tool call item that failed. + The reasoning text from the model. - - `output_index: number` + - `type: "reasoning_text"` - The index of the output item that failed. + The type of the reasoning text. Always `reasoning_text`. - - `sequence_number: number` + - `"reasoning_text"` - The sequence number of this event. + - `encrypted_content: optional string` - - `type: "response.mcp_list_tools.failed"` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - The type of the event. Always 'response.mcp_list_tools.failed'. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"response.mcp_list_tools.failed"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `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. + - `Program object { id, call_id, code, 3 more }` - - `BetaResponseMcpListToolsInProgressEvent object { item_id, output_index, sequence_number, 2 more }` + - `id: string` - Emitted when the system is in the process of retrieving the list of available MCP tools. + The unique ID of the program item. - - `item_id: string` + - `call_id: string` - The ID of the MCP tool call item that is being processed. + The stable call ID of the program item. - - `output_index: number` + - `code: string` - The index of the output item that is being processed. + The JavaScript source executed by programmatic tool calling. - - `sequence_number: number` + - `fingerprint: string` - The sequence number of this event. + Opaque program replay fingerprint that must be round-tripped. - - `type: "response.mcp_list_tools.in_progress"` + - `type: "program"` - The type of the event. Always 'response.mcp_list_tools.in_progress'. + The type of the item. Always `program`. - - `"response.mcp_list_tools.in_progress"` + - `"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. - - `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.) + - `ProgramOutput object { id, call_id, result, 3 more }` - - `annotation_index: number` + - `id: string` - The index of the annotation within the content part. + The unique ID of the program output item. - - `content_index: number` + - `call_id: string` - The index of the content part within the output item. + The call ID of the program item. - - `item_id: string` + - `result: string` - The unique identifier of the item to which the annotation is being added. + The result produced by the program item. - - `output_index: number` + - `status: "completed" or "incomplete"` - The index of the output item in the response's output array. + The terminal status of the program output item. - - `sequence_number: number` + - `"completed"` - The sequence number of this event. + - `"incomplete"` - - `type: "response.output_text.annotation.added"` + - `type: "program_output"` - The type of the event. Always 'response.output_text.annotation.added'. + The type of the item. Always `program_output`. - - `"response.output_text.annotation.added"` + - `"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. - - `BetaResponseQueuedEvent object { response, sequence_number, type, agent }` + - `ToolSearchCall object { id, arguments, call_id, 5 more }` - Emitted when a response is queued and waiting to be processed. + - `id: string` - - `response: BetaResponse` + The unique ID of the tool search call item. - The full response object that is queued. + - `arguments: unknown` - - `sequence_number: number` + Arguments used for the tool search call. - The sequence number for this event. + - `call_id: string` - - `type: "response.queued"` + The unique ID of the tool search call generated by the model. - The type of the event. Always 'response.queued'. + - `execution: "server" or "client"` - - `"response.queued"` + 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 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. - - `BetaResponseCustomToolCallInputDeltaEvent object { delta, item_id, output_index, 3 more }` - - Event representing a delta (partial update) to the input of a custom tool call. + - `created_by: optional string` - - `delta: string` + The identifier of the actor that created the item. - The incremental input data (delta) for the custom tool call. + - `ToolSearchOutput object { id, call_id, execution, 5 more }` - - `item_id: string` + - `id: string` - Unique identifier for the API item associated with this event. + The unique ID of the tool search output item. - - `output_index: number` + - `call_id: string` - The index of the output this delta applies to. + The unique ID of the tool search call generated by the model. - - `sequence_number: number` + - `execution: "server" or "client"` - The sequence number of this event. + Whether tool search was executed by the server or by the client. - - `type: "response.custom_tool_call_input.delta"` + - `"server"` - The event type identifier. + - `"client"` - - `"response.custom_tool_call_input.delta"` + - `status: "in_progress" or "completed" or "incomplete"` - - `agent: optional object { agent_name }` + The status of the tool search output item that was recorded. - 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"` - - `BetaResponseCustomToolCallInputDoneEvent object { input, item_id, output_index, 3 more }` + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - Event indicating that input for a custom tool call is complete. + The loaded tool definitions returned by tool search. - - `input: string` + - `Function object { name, parameters, strict, 5 more }` - The complete input data for the custom 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). - - `item_id: string` + - `name: string` - Unique identifier for the API item associated with this event. + The name of the function to call. - - `output_index: number` + - `parameters: map[unknown]` - The index of the output this event applies to. + 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. - - `type: "response.custom_tool_call_input.done"` + - `type: "function"` - The event type identifier. + The type of the function tool. Always `function`. - - `"response.custom_tool_call_input.done"` + - `"function"` - - `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"` -### Beta Response Text Config + - `defer_loading: optional boolean` -- `BetaResponseTextConfig object { format, verbosity }` + Whether this function is deferred and loaded 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](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + A description of the function. Used by the model to determine whether or not to call the function. - - `format: optional BetaResponseFormatTextConfig` + - `output_schema: optional map[unknown]` - An object specifying the format that the model must output. + A JSON schema object describing the JSON value encoded in string outputs for this function. - Configuring `{ "type": "json_schema" }` enables Structured Outputs, - which ensures the model will match your supplied JSON schema. Learn more in the - [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - The default format is `{ "type": "text" }` with no additional options. + 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). - **Not recommended for gpt-4o and newer models:** + - `type: "file_search"` - 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 type of the file search tool. Always `file_search`. - - `Text object { type }` + - `"file_search"` - Default response format. Used to generate text responses. + - `vector_store_ids: array of string` - - `type: "text"` + The IDs of the vector stores to search. - The type of response format being defined. Always `text`. + - `filters: optional object { key, type, value } or object { filters, type }` - - `"text"` + A filter to apply. - - `BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` + - `ComparisonFilter object { key, type, value }` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `name: string` + - `key: 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 key to compare against the value. - - `schema: map[unknown]` + - `type: "eq" or "ne" or "gt" or 5 more` - 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 comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `type: "json_schema"` + - `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 response format being defined. Always `json_schema`. + - `"eq"` - - `"json_schema"` + - `"ne"` - - `description: optional string` + - `"gt"` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `"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](https://platform.openai.com/docs/guides/structured-outputs). + - `"lte"` - - `JSONObject object { type }` + - `"in"` - 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. + - `"nin"` - - `type: "json_object"` + - `value: string or number or boolean or array of string or number` - The type of response format being defined. Always `json_object`. + The value to compare against the attribute key; supports string, number, or boolean types. - - `"json_object"` + - `string` - - `verbosity: optional "low" or "medium" or "high"` + - `number` - 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`. + - `boolean` - - `"low"` + - `array of string or number` - - `"medium"` + - `string` - - `"high"` + - `number` -### Beta Response Text Delta Event + - `CompoundFilter object { filters, type }` -- `BetaResponseTextDeltaEvent object { content_index, delta, item_id, 5 more }` + Combine multiple filters using `and` or `or`. - Emitted when there is an additional text delta. + - `filters: array of object { key, type, value } or unknown` - - `content_index: number` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - The index of the content part that the text delta was added to. + - `ComparisonFilter object { key, type, value }` - - `delta: string` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The text delta that was added. + - `key: string` - - `item_id: string` + The key to compare against the value. - The ID of the output item that the text delta was added to. + - `type: "eq" or "ne" or "gt" or 5 more` - - `logprobs: array of object { token, logprob, top_logprobs }` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The log probabilities of the tokens in the delta. + - `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 - - `token: string` + - `"eq"` - A possible text token. + - `"ne"` - - `logprob: number` + - `"gt"` - The log probability of this token. + - `"gte"` - - `top_logprobs: optional array of object { token, logprob }` + - `"lt"` - The log probabilities of up to 20 of the most likely tokens. + - `"lte"` - - `token: optional string` + - `"in"` - A possible text token. + - `"nin"` - - `logprob: optional number` + - `value: string or number or boolean or array of string or number` - The log probability of this token. + The value to compare against the attribute key; supports string, number, or boolean types. - - `output_index: number` + - `string` - The index of the output item that the text delta was added to. + - `number` - - `sequence_number: number` + - `boolean` - The sequence number for this event. + - `array of string or number` - - `type: "response.output_text.delta"` + - `string` - The type of the event. Always `response.output_text.delta`. + - `number` - - `"response.output_text.delta"` + - `unknown` - - `agent: optional object { agent_name }` + - `type: "and" or "or"` - The agent that owns this multi-agent streaming event. + Type of operation: `and` or `or`. - - `agent_name: string` + - `"and"` - The canonical name of the agent that produced this item. + - `"or"` -### Beta Response Text Done Event + - `max_num_results: optional number` -- `BetaResponseTextDoneEvent object { content_index, item_id, logprobs, 5 more }` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - Emitted when text content is finalized. + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `content_index: number` + Ranking options for search. - The index of the content part that the text content is finalized. + - `hybrid_search: optional object { embedding_weight, text_weight }` - - `item_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 output item that the text content is finalized. + - `embedding_weight: number` - - `logprobs: array of object { token, logprob, top_logprobs }` + The weight of the embedding in the reciprocal ranking fusion. - The log probabilities of the tokens in the delta. + - `text_weight: number` - - `token: string` + The weight of the text in the reciprocal ranking fusion. - A possible text token. + - `ranker: optional "auto" or "default-2024-11-15"` - - `logprob: number` + The ranker to use for the file search. - The log probability of this token. + - `"auto"` - - `top_logprobs: optional array of object { token, logprob }` + - `"default-2024-11-15"` - The log probabilities of up to 20 of the most likely tokens. + - `score_threshold: optional number` - - `token: optional string` + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - A possible text token. + - `Computer object { type }` - - `logprob: optional number` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The log probability of this token. + - `type: "computer"` - - `output_index: number` + The type of the computer tool. Always `computer`. - The index of the output item that the text content is finalized. + - `"computer"` - - `sequence_number: number` + - `ComputerUsePreview object { display_height, display_width, environment, 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). - - `text: string` + - `display_height: number` - The text content that is finalized. + The height of the computer display. - - `type: "response.output_text.done"` + - `display_width: number` - The type of the event. Always `response.output_text.done`. + The width of the computer display. - - `"response.output_text.done"` + - `environment: "windows" or "mac" or "linux" or 2 more` - - `agent: optional object { agent_name }` + The type of computer environment to control. - The agent that owns this multi-agent streaming event. + - `"windows"` - - `agent_name: string` + - `"mac"` - The canonical name of the agent that produced this item. + - `"linux"` -### Beta Response Usage + - `"ubuntu"` -- `BetaResponseUsage object { input_tokens, input_tokens_details, output_tokens, 2 more }` + - `"browser"` - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + - `type: "computer_use_preview"` - - `input_tokens: number` + The type of the computer use tool. Always `computer_use_preview`. - The number of input tokens. + - `"computer_use_preview"` - - `input_tokens_details: object { cache_write_tokens, cached_tokens }` + - `WebSearch object { type, filters, search_context_size, user_location }` - A detailed breakdown of the input tokens. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - - `cache_write_tokens: number` + - `type: "web_search" or "web_search_2025_08_26"` - The number of input tokens that were written to the cache. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `cached_tokens: number` + - `"web_search"` - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + - `"web_search_2025_08_26"` - - `output_tokens: number` + - `filters: optional object { allowed_domains }` - The number of output tokens. + Filters for the search. - - `output_tokens_details: object { reasoning_tokens }` + - `allowed_domains: optional array of string` - A detailed breakdown of the output tokens. + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `reasoning_tokens: number` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - The number of reasoning tokens. + - `search_context_size: optional "low" or "medium" or "high"` - - `total_tokens: 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 total number of tokens used. + - `"low"` -### Beta Response Web Search Call Completed Event + - `"medium"` -- `BetaResponseWebSearchCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` + - `"high"` - Emitted when a web search call is completed. + - `user_location: optional object { city, country, region, 2 more }` - - `item_id: string` + The approximate location of the user. - Unique ID for the output item associated with the web search call. + - `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 the web search call is associated with. + - `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 web search call being processed. + - `region: optional string` - - `type: "response.web_search_call.completed"` + Free text input for the region of the user, e.g. `California`. - The type of the event. Always `response.web_search_call.completed`. + - `timezone: optional string` - - `"response.web_search_call.completed"` + 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 }` -### Beta Response Web Search Call In Progress Event + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). -- `BetaResponseWebSearchCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` + - `server_label: string` - Emitted when a web search call is initiated. + A label for this MCP server, used to identify it in tool calls. - - `item_id: string` + - `type: "mcp"` - Unique ID for the output item associated with the web search call. + The type of the MCP tool. Always `mcp`. - - `output_index: number` + - `"mcp"` - The index of the output item that the web search call is associated with. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `sequence_number: number` + The tool invocation context(s). - The sequence number of the web search call being processed. + - `"direct"` - - `type: "response.web_search_call.in_progress"` + - `"programmatic"` - The type of the event. Always `response.web_search_call.in_progress`. + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `"response.web_search_call.in_progress"` + List of allowed tool names or a filter object. - - `agent: optional object { agent_name }` + - `McpAllowedTools = array of string` - The agent that owns this multi-agent streaming event. + 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. -### Beta Response Web Search Call Searching Event + - `read_only: optional boolean` -- `BetaResponseWebSearchCallSearchingEvent object { item_id, output_index, sequence_number, 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. - Emitted when a web search call is executing. + - `tool_names: optional array of string` - - `item_id: string` + List of allowed tool names. - Unique ID for the output item associated with the web search call. + - `authorization: optional string` - - `output_index: 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. - The index of the output item that the web search call is associated with. + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `sequence_number: 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 sequence number of the web search call being processed. + Currently supported `connector_id` values are: - - `type: "response.web_search_call.searching"` + - 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 event. Always `response.web_search_call.searching`. + - `"connector_dropbox"` - - `"response.web_search_call.searching"` + - `"connector_gmail"` - - `agent: optional object { agent_name }` + - `"connector_googlecalendar"` - The agent that owns this multi-agent streaming event. + - `"connector_googledrive"` - - `agent_name: string` + - `"connector_microsoftteams"` - The canonical name of the agent that produced this item. + - `"connector_outlookcalendar"` -### Beta Responses Client Event + - `"connector_outlookemail"` -- `BetaResponsesClientEvent = object { type, background, context_management, 30 more } or object { input, response_id, type }` + - `"connector_sharepoint"` - Client events accepted by the Responses WebSocket server. + - `defer_loading: optional boolean` - - `ResponseCreate object { type, background, context_management, 30 more }` + Whether this MCP tool is deferred and discovered via tool search. - Client event for creating a response over a persistent WebSocket connection. - This payload uses the same top-level fields as `POST /v1/responses`. + - `headers: optional map[string]` - Notes: + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `stream` is implicit over WebSocket and should not be sent. - - `background` is not supported over WebSocket. + - `require_approval: optional object { always, never } or "always" or "never"` - - `type: "response.create"` + Specify which of the MCP server's tools require approval. - The type of the client event. Always `response.create`. + - `McpToolApprovalFilter object { always, never }` - - `"response.create"` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `background: optional boolean` + - `always: optional object { read_only, tool_names }` - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + A filter object to specify which tools are allowed. - - `context_management: optional array of object { type, compact_threshold }` + - `read_only: optional boolean` - Context management configuration for this request. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `type: string` + - `tool_names: optional array of string` - The context management entry type. Currently only 'compaction' is supported. + List of allowed tool names. - - `compact_threshold: optional number` + - `never: optional object { read_only, tool_names }` - Token threshold at which compaction should be triggered for this entry. + A filter object to specify which tools are allowed. - - `conversation: optional string or BetaResponseConversationParam` + - `read_only: optional boolean` - 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. + 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. - - `ConversationID = string` + - `tool_names: optional array of string` - The unique ID of the conversation. + List of allowed tool names. - - `BetaResponseConversationParam object { id }` + - `McpToolApprovalSetting = "always" or "never"` - The conversation that this response belongs to. + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - - `id: string` + - `"always"` - The unique ID of the conversation. + - `"never"` - - `include: optional array of BetaResponseIncludable` + - `server_description: optional string` - Specify additional output data to include in the model response. Currently supported values are: + Optional description of the MCP server, used to provide more context. - - `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). + - `server_url: optional string` - - `"file_search_call.results"` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `"web_search_call.results"` + - `tunnel_id: optional string` - - `"web_search_call.action.sources"` + 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. - - `"message.input_image.image_url"` + - `CodeInterpreter object { container, type, allowed_callers }` - - `"computer_call_output.output.image_url"` + A tool that runs Python code to help generate a response to a prompt. - - `"code_interpreter_call.outputs"` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `"reasoning.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. - - `"message.output_text.logprobs"` + - `string` - - `input: optional string or BetaResponseInput` + The container ID. - Text, image, or file inputs to the model, used to generate a response. + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - Learn more: + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Image inputs](https://platform.openai.com/docs/guides/images) - - [File inputs](https://platform.openai.com/docs/guides/pdf-files) - - [Conversation state](https://platform.openai.com/docs/guides/conversation-state) - - [Function calling](https://platform.openai.com/docs/guides/function-calling) + - `type: "auto"` - - `TextInput = string` + Always `auto`. - A text input to the model, equivalent to a text input with the - `user` role. + - `"auto"` - - `BetaResponseInput = array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + - `file_ids: optional array of string` - A list of one or many input items to the model, containing - different content types. + An optional list of uploaded files to make available to your code. - - `BetaEasyInputMessage object { content, role, phase, type }` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - 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 memory limit for the code interpreter container. - - `content: string or BetaResponseInputMessageContentList` + - `"1g"` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + - `"4g"` - - `TextInput = string` + - `"16g"` - A text input to the model. + - `"64g"` - - `BetaResponseInputMessageContentList = array of BetaResponseInputContent` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - A list of one or many input items to the model, containing different content - types. + Network access policy for the container. - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `BetaContainerNetworkPolicyDisabled object { type }` - A text input to the model. + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `text: string` + - `type: "code_interpreter"` - The text input to the model. + The type of the code interpreter tool. Always `code_interpreter`. - - `type: "input_text"` + - `"code_interpreter"` - The type of the input item. Always `input_text`. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"input_text"` + 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`. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `"programmatic_tool_calling"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `ImageGeneration object { type, action, background, 9 more }` - - `detail: "low" or "high" or "auto" or "original"` + A tool that generates images using the GPT image models. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `type: "image_generation"` - - `"low"` + The type of the image generation tool. Always `image_generation`. - - `"high"` + - `"image_generation"` - - `"auto"` + - `action: optional "generate" or "edit" or "auto"` - - `"original"` + Whether to generate a new image or edit an existing image. Default: `auto`. - - `type: "input_image"` + - `"generate"` - The type of the input item. Always `input_image`. + - `"edit"` - - `"input_image"` + - `"auto"` - - `file_id: optional string` + - `background: optional "transparent" or "opaque" or "auto"` - The ID of the file to be sent to the model. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - - `image_url: optional string` + - `"transparent"` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `"opaque"` - - `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. + - `input_fidelity: optional "high" or "low"` - - `mode: "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`. - The breakpoint mode. Always `explicit`. + - `"high"` - - `"explicit"` + - `"low"` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `input_image_mask: optional object { file_id, image_url }` - A file input to the model. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `type: "input_file"` + - `file_id: optional string` - The type of the input item. Always `input_file`. + File ID for the mask image. - - `"input_file"` + - `image_url: optional string` - - `detail: optional "auto" or "low" or "high"` + Base64-encoded 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`. + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `"auto"` + The image generation model to use. Default: `gpt-image-1`. - - `"low"` + - `string` - - `"high"` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `file_data: optional string` + The image generation model to use. Default: `gpt-image-1`. - The content of the file to be sent to the model. + - `"gpt-image-1"` - - `file_id: optional string` + - `"gpt-image-1-mini"` - The ID of the file to be sent to the model. + - `"gpt-image-1.5"` - - `file_url: optional string` + - `moderation: optional "auto" or "low"` - The URL of the file to be sent to the model. + Moderation level for the generated image. Default: `auto`. - - `filename: optional string` + - `"auto"` - The name of the file to be sent to the model. + - `"low"` - - `prompt_cache_breakpoint: optional object { mode }` + - `output_compression: 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. + Compression level for the output image. Default: 100. - - `mode: "explicit"` + - `output_format: optional "png" or "webp" or "jpeg"` - The breakpoint mode. Always `explicit`. + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `"explicit"` + - `"png"` - - `role: "user" or "assistant" or "system" or "developer"` + - `"webp"` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + - `"jpeg"` - - `"user"` + - `partial_images: optional number` - - `"assistant"` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `"system"` + - `quality: optional "low" or "medium" or "high" or "auto"` - - `"developer"` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `phase: optional "commentary" or "final_answer"` + - `"low"` - 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. + - `"medium"` - - `"commentary"` + - `"high"` - - `"final_answer"` + - `"auto"` - - `type: optional "message"` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - The type of the message input. Always `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`. - - `"message"` + - `string` - - `Message object { content, role, agent, 2 more }` + - `"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. + 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: BetaResponseInputMessageContentList` + - `"1024x1024"` - A list of one or many input items to the model, containing different content - types. + - `"1024x1536"` - - `role: "user" or "system" or "developer"` + - `"1536x1024"` - The role of the message input. One of `user`, `system`, or `developer`. + - `"auto"` - - `"user"` + - `LocalShell object { type }` - - `"system"` + A tool that allows the model to execute shell commands in a local environment. - - `"developer"` + - `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. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `type: "shell"` - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The type of the shell tool. Always `shell`. - - `"in_progress"` + - `"shell"` - - `"completed"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"incomplete"` + The tool invocation context(s). - - `type: optional "message"` + - `"direct"` - The type of the message input. Always set to `message`. + - `"programmatic"` - - `"message"` + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - `BetaResponseOutputMessage object { id, content, role, 4 more }` + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - An output message from the model. + - `BetaLocalEnvironment object { type, skills }` - - `id: string` + - `BetaContainerReference object { container_id, type }` - The unique ID of the output message. + - `Custom object { name, type, allowed_callers, 3 more }` - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - The content of the output message. + - `name: string` - - `BetaResponseOutputText object { annotations, text, type, logprobs }` + The name of the custom tool, used to identify it in tool calls. - A text output from the model. + - `type: "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 }` + The type of the custom tool. Always `custom`. - The annotations of the text output. + - `"custom"` - - `FileCitation object { file_id, filename, index, type }` + - `allowed_callers: optional array of "direct" or "programmatic"` - A citation to a file. + The tool invocation context(s). - - `file_id: string` + - `"direct"` - The ID of the file. + - `"programmatic"` - - `filename: string` + - `defer_loading: optional boolean` - The filename of the file cited. + Whether this tool should be deferred and discovered via tool search. - - `index: number` + - `description: optional string` - The index of the file in the list of files. + Optional description of the custom tool, used to provide more context. - - `type: "file_citation"` + - `format: optional object { type } or object { definition, syntax, type }` - The type of the file citation. Always `file_citation`. + The input format for the custom tool. Default is unconstrained text. - - `"file_citation"` + - `Text object { type }` - - `URLCitation object { end_index, start_index, title, 2 more }` + Unconstrained free-form text. - A citation for a web resource used to generate a model response. + - `type: "text"` - - `end_index: number` + Unconstrained text format. Always `text`. - The index of the last character of the URL citation in the message. + - `"text"` - - `start_index: number` + - `Grammar object { definition, syntax, type }` - The index of the first character of the URL citation in the message. + A grammar defined by the user. - - `title: string` + - `definition: string` - The title of the web resource. + The grammar definition. - - `type: "url_citation"` + - `syntax: "lark" or "regex"` - The type of the URL citation. Always `url_citation`. + The syntax of the grammar definition. One of `lark` or `regex`. - - `"url_citation"` + - `"lark"` - - `url: string` + - `"regex"` - The URL of the web resource. + - `type: "grammar"` - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + Grammar format. Always `grammar`. - A citation for a container file used to generate a model response. + - `"grammar"` - - `container_id: string` + - `Namespace object { description, name, tools, type }` - The ID of the container file. + Groups function/custom tools under a shared namespace. - - `end_index: number` + - `description: string` - The index of the last character of the container file citation in the message. + A description of the namespace shown to the model. - - `file_id: string` + - `name: string` - The ID of the file. + The namespace name used in tool calls (for example, `crm`). - - `filename: string` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - The filename of the container file cited. + The function/custom tools available inside this namespace. - - `start_index: number` + - `Function object { name, type, allowed_callers, 5 more }` - The index of the first character of the container file citation in the message. + - `name: string` - - `type: "container_file_citation"` + - `type: "function"` - The type of the container file citation. Always `container_file_citation`. + - `"function"` - - `"container_file_citation"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `FilePath object { file_id, index, type }` + The tool invocation context(s). - A path to a file. + - `"direct"` - - `file_id: string` + - `"programmatic"` - The ID of the file. + - `defer_loading: optional boolean` - - `index: number` + Whether this function should be deferred and discovered via tool search. - The index of the file in the list of files. + - `description: optional string` - - `type: "file_path"` + - `output_schema: optional map[unknown]` - The type of the file path. Always `file_path`. + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `"file_path"` + - `parameters: optional unknown` - - `text: string` + - `strict: optional boolean` - The text output from the model. + 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: "output_text"` + - `Custom object { name, type, allowed_callers, 3 more }` - The type of the output text. Always `output_text`. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `"output_text"` + - `name: string` - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + The name of the custom tool, used to identify it in tool calls. - - `token: string` + - `type: "custom"` - - `bytes: array of number` + The type of the custom tool. Always `custom`. - - `logprob: number` + - `"custom"` - - `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"` - - `BetaResponseOutputRefusal object { refusal, type }` + - `defer_loading: optional boolean` - A refusal from the model. + Whether this tool should be deferred and discovered via tool search. - - `refusal: string` + - `description: optional string` - The refusal explanation from the model. + Optional description of the custom tool, used to provide more context. - - `type: "refusal"` + - `format: optional object { type } or object { definition, syntax, type }` - The type of the refusal. Always `refusal`. + The input format for the custom tool. Default is unconstrained text. - - `"refusal"` + - `Text object { type }` - - `role: "assistant"` + Unconstrained free-form text. - The role of the output message. Always `assistant`. + - `type: "text"` - - `"assistant"` + Unconstrained text format. Always `text`. - - `status: "in_progress" or "completed" or "incomplete"` + - `"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 }` - - `"in_progress"` + A grammar defined by the user. - - `"completed"` + - `definition: string` - - `"incomplete"` + The grammar definition. - - `type: "message"` + - `syntax: "lark" or "regex"` - The type of the output message. Always `message`. + The syntax of the grammar definition. One of `lark` or `regex`. - - `"message"` + - `"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"` - - `phase: optional "commentary" or "final_answer"` + - `type: "namespace"` - 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 tool. Always `namespace`. - - `"commentary"` + - `"namespace"` - - `"final_answer"` + - `ToolSearch object { type, description, execution, parameters }` - - `FileSearchCall object { id, queries, status, 3 more }` + Hosted or BYOT tool search configuration for deferred tools. - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `type: "tool_search"` - - `id: string` + The type of the tool. Always `tool_search`. - The unique ID of the file search tool call. + - `"tool_search"` - - `queries: array of string` + - `description: optional string` - The queries used to search for files. + Description shown to the model for a client-executed tool search tool. - - `status: "in_progress" or "searching" or "completed" or 2 more` + - `execution: optional "server" or "client"` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + Whether tool search is executed by the server or by the client. - - `"in_progress"` + - `"server"` - - `"searching"` + - `"client"` - - `"completed"` + - `parameters: optional unknown` - - `"incomplete"` + Parameter schema for a client-executed tool search tool. - - `"failed"` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - - `type: "file_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). - The type of the file search tool call. Always `file_search_call`. + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `"file_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"` - - `results: optional array of object { attributes, file_id, filename, 2 more }` + - `"image"` - The results of the file search tool call. + - `search_context_size: optional "low" or "medium" or "high"` - - `attributes: optional map[string or number or 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. - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. Keys are strings - with a maximum length of 64 characters. Values are strings with a maximum - length of 512 characters, booleans, or numbers. + - `"low"` - - `string` + - `"medium"` - - `number` + - `"high"` - - `boolean` + - `user_location: optional object { type, city, country, 2 more }` - - `file_id: optional string` + The user's location. - The unique ID of the file. + - `type: "approximate"` - - `filename: optional string` + The type of location approximation. Always `approximate`. - The name of the file. + - `"approximate"` - - `score: optional number` + - `city: optional string` - The relevance score of the file - a value between 0 and 1. + Free text input for the city of the user, e.g. `San Francisco`. - - `text: optional string` + - `country: optional string` - The text that was retrieved from the file. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` + - `region: optional string` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + Free text input for the region of the user, e.g. `California`. - - `id: string` + - `timezone: optional string` - The unique ID of the computer 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 }` - An identifier used when responding to the tool call with output. + Allows the assistant to create, delete, or update files using unified diffs. - - `pending_safety_checks: array of object { id, code, message }` + - `type: "apply_patch"` - The pending safety checks for the computer call. + The type of the tool. Always `apply_patch`. - - `id: string` + - `"apply_patch"` - 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. + - `type: "tool_search_output"` - - `status: "in_progress" or "completed" or "incomplete"` + The type of the item. Always `tool_search_output`. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"tool_search_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`. + - `created_by: optional string` - - `"computer_call"` + The identifier of the actor that created the item. - - `action: optional BetaComputerAction` + - `AdditionalTools object { id, role, tools, 2 more }` - A click action. + - `id: string` - - `Click object { button, type, x, 2 more }` + The unique ID of the additional tools item. - A click action. + - `role: "unknown" or "user" or "assistant" or 5 more` - - `button: "left" or "right" or "wheel" or 2 more` + The role that provided the additional tools. - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `"unknown"` - - `"left"` + - `"user"` - - `"right"` + - `"assistant"` - - `"wheel"` + - `"system"` - - `"back"` + - `"critic"` - - `"forward"` + - `"discriminator"` - - `type: "click"` + - `"developer"` - Specifies the event type. For a click action, this property is always `click`. + - `"tool"` - - `"click"` + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - - `x: number` + The additional tool definitions made available at this item. - The x-coordinate where the click occurred. + - `Function object { name, parameters, strict, 5 more }` - - `y: 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 y-coordinate where the click occurred. + - `name: string` - - `keys: optional array of string` + The name of the function to call. - The keys being held while clicking. + - `parameters: map[unknown]` - - `DoubleClick object { keys, type, x, y }` + A JSON schema object describing the parameters of the function. - A double click action. + - `strict: boolean` - - `keys: array of string` + Whether strict parameter validation is enforced for this function tool. - The keys being held while double-clicking. + - `type: "function"` - - `type: "double_click"` + The type of the function tool. Always `function`. - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `"function"` - - `"double_click"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `x: number` + The tool invocation context(s). - The x-coordinate where the double click occurred. + - `"direct"` - - `y: number` + - `"programmatic"` - The y-coordinate where the double click occurred. + - `defer_loading: optional boolean` - - `Drag object { path, type, keys }` + Whether this function is deferred and loaded via tool search. - A drag action. + - `description: optional string` - - `path: array of object { x, y }` + A description of the function. Used by the model to determine whether or not to call the function. - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `output_schema: optional map[unknown]` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `x: number` + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - The x-coordinate. + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `y: number` + - `type: "file_search"` - The y-coordinate. + The type of the file search tool. Always `file_search`. - - `type: "drag"` + - `"file_search"` - Specifies the event type. For a drag action, this property is always set to `drag`. + - `vector_store_ids: array of string` - - `"drag"` + The IDs of the vector stores to search. - - `keys: optional array of string` + - `filters: optional object { key, type, value } or object { filters, type }` - The keys being held while dragging the mouse. + A filter to apply. - - `Keypress object { keys, type }` + - `ComparisonFilter object { key, type, value }` - A collection of keypresses the model would like to perform. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `keys: array of string` + - `key: string` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + The key to compare against the value. - - `type: "keypress"` + - `type: "eq" or "ne" or "gt" or 5 more` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `"keypress"` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `Move object { type, x, y, keys }` + - `"eq"` - A mouse move action. + - `"ne"` - - `type: "move"` + - `"gt"` - Specifies the event type. For a move action, this property is always set to `move`. + - `"gte"` - - `"move"` + - `"lt"` - - `x: number` + - `"lte"` - The x-coordinate to move to. + - `"in"` - - `y: number` + - `"nin"` - The y-coordinate to move to. + - `value: string or number or boolean or array of string or number` - - `keys: optional array of string` + The value to compare against the attribute key; supports string, number, or boolean types. - The keys being held while moving the mouse. + - `string` - - `Screenshot object { type }` + - `number` - A screenshot action. + - `boolean` - - `type: "screenshot"` + - `array of string or number` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `string` - - `"screenshot"` + - `number` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `CompoundFilter object { filters, type }` - A scroll action. + Combine multiple filters using `and` or `or`. - - `scroll_x: number` + - `filters: array of object { key, type, value } or unknown` - The horizontal scroll distance. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `scroll_y: number` + - `ComparisonFilter object { key, type, value }` - The vertical scroll distance. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `type: "scroll"` + - `key: string` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + The key to compare against the value. - - `"scroll"` + - `type: "eq" or "ne" or "gt" or 5 more` - - `x: number` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The x-coordinate where the scroll 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 - - `y: number` + - `"eq"` - The y-coordinate where the scroll occurred. + - `"ne"` - - `keys: optional array of string` + - `"gt"` - The keys being held while scrolling. + - `"gte"` - - `Type object { text, type }` + - `"lt"` - An action to type in text. + - `"lte"` - - `text: string` + - `"in"` - The text to type. + - `"nin"` - - `type: "type"` + - `value: string or number or boolean or array of string or number` - Specifies the event type. For a type action, this property is always set to `type`. + The value to compare against the attribute key; supports string, number, or boolean types. - - `"type"` + - `string` - - `Wait object { type }` + - `number` - A wait action. + - `boolean` - - `type: "wait"` + - `array of string or number` - Specifies the event type. For a wait action, this property is always set to `wait`. + - `string` - - `"wait"` + - `number` - - `actions: optional BetaComputerActionList` + - `unknown` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `type: "and" or "or"` - - `Click object { button, type, x, 2 more }` + Type of operation: `and` or `or`. - A click action. + - `"and"` - - `DoubleClick object { keys, type, x, y }` + - `"or"` - A double click action. + - `max_num_results: optional number` - - `Drag object { path, type, keys }` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - A drag action. + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `Keypress object { keys, type }` + Ranking options for search. - A collection of keypresses the model would like to perform. + - `hybrid_search: optional object { embedding_weight, text_weight }` - - `Move object { type, x, y, keys }` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - A mouse move action. + - `embedding_weight: number` - - `Screenshot object { type }` + The weight of the embedding in the reciprocal ranking fusion. - A screenshot action. + - `text_weight: number` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + The weight of the text in the reciprocal ranking fusion. - A scroll action. + - `ranker: optional "auto" or "default-2024-11-15"` - - `Type object { text, type }` + The ranker to use for the file search. - An action to type in text. + - `"auto"` - - `Wait object { type }` + - `"default-2024-11-15"` - A wait action. + - `score_threshold: optional number` - - `agent: optional object { agent_name }` + 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 agent that produced this item. + - `Computer object { type }` - - `agent_name: string` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The canonical name of the agent that produced this item. + - `type: "computer"` - - `ComputerCallOutput object { call_id, output, type, 4 more }` + The type of the computer tool. Always `computer`. - The output of a computer tool call. + - `"computer"` - - `call_id: string` + - `ComputerUsePreview object { display_height, display_width, environment, type }` - The ID of the computer tool call that produced the output. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `display_height: number` - A computer screenshot image used with the computer use tool. + The height of the computer display. - - `type: "computer_screenshot"` + - `display_width: number` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + The width of the computer display. - - `"computer_screenshot"` + - `environment: "windows" or "mac" or "linux" or 2 more` - - `file_id: optional string` + The type of computer environment to control. - The identifier of an uploaded file that contains the screenshot. + - `"windows"` - - `image_url: optional string` + - `"mac"` - The URL of the screenshot image. + - `"linux"` - - `type: "computer_call_output"` + - `"ubuntu"` - The type of the computer tool call output. Always `computer_call_output`. + - `"browser"` - - `"computer_call_output"` + - `type: "computer_use_preview"` - - `id: optional string` + The type of the computer use tool. Always `computer_use_preview`. - The ID of the computer tool call output. + - `"computer_use_preview"` - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `WebSearch object { type, filters, search_context_size, user_location }` - The safety checks reported by the API that have been acknowledged by the developer. + 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 ID of the pending safety check. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `code: optional string` + - `"web_search"` - The type of the pending safety check. + - `"web_search_2025_08_26"` - - `message: optional string` + - `filters: optional object { allowed_domains }` - Details about the pending safety check. + Filters for the search. - - `agent: optional object { agent_name }` + - `allowed_domains: optional array of string` - 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. - - `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"` - - `status: optional "in_progress" or "completed" or "incomplete"` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + - `"low"` - - `"in_progress"` + - `"medium"` - - `"completed"` + - `"high"` - - `"incomplete"` + - `user_location: optional object { city, country, region, 2 more }` - - `WebSearchCall object { id, action, status, 2 more }` + The approximate location of the user. - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `city: optional string` - - `id: string` + Free text input for the city of the user, e.g. `San Francisco`. - The unique ID of the web search tool call. + - `country: optional string` - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - 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). + - `region: optional string` - - `Search object { type, queries, query, sources }` + Free text input for the region of the user, e.g. `California`. - Action type "search" - Performs a web search query. + - `timezone: optional string` - - `type: "search"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The action type. + - `type: optional "approximate"` - - `"search"` + The type of location approximation. Always `approximate`. - - `queries: optional array of string` + - `"approximate"` - The search queries. + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `query: 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 search query. + - `server_label: string` - - `sources: optional array of object { type, url }` + A label for this MCP server, used to identify it in tool calls. - The sources used in the search. + - `type: "mcp"` - - `type: "url"` + The type of the MCP tool. Always `mcp`. - The type of source. Always `url`. + - `"mcp"` - - `"url"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `url: string` + The tool invocation context(s). - The URL of the source. + - `"direct"` - - `OpenPage object { type, url }` + - `"programmatic"` - Action type "open_page" - Opens a specific URL from search results. + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `type: "open_page"` + List of allowed tool names or a filter object. - The action type. + - `McpAllowedTools = array of string` - - `"open_page"` + A string array of allowed tool names - - `url: optional string` + - `McpToolFilter object { read_only, tool_names }` - The URL opened by the model. + A filter object to specify which tools are allowed. - - `FindInPage object { pattern, type, url }` + - `read_only: optional boolean` - Action type "find_in_page": Searches for a pattern within a loaded 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. - - `pattern: string` + - `tool_names: optional array of string` - The pattern or text to search for within the page. + List of allowed tool names. - - `type: "find_in_page"` + - `authorization: optional string` - The action 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. - - `"find_in_page"` + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `url: 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 URL of the page searched for the pattern. + Currently supported `connector_id` values are: - - `status: "in_progress" or "searching" or "completed" or "failed"` + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - The status of the web search tool call. + - `"connector_dropbox"` - - `"in_progress"` + - `"connector_gmail"` - - `"searching"` + - `"connector_googlecalendar"` - - `"completed"` + - `"connector_googledrive"` - - `"failed"` + - `"connector_microsoftteams"` - - `type: "web_search_call"` + - `"connector_outlookcalendar"` - The type of the web search tool call. Always `web_search_call`. + - `"connector_outlookemail"` - - `"web_search_call"` + - `"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. - - `FunctionCall object { arguments, call_id, name, 6 more }` + - `require_approval: optional object { always, never } or "always" or "never"` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + Specify which of the MCP server's tools require approval. - - `arguments: string` + - `McpToolApprovalFilter object { always, never }` - A JSON string of the arguments to pass to the function. + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `call_id: string` + - `always: optional object { read_only, tool_names }` - The unique ID of the function tool call generated by the model. + A filter object to specify which tools are allowed. - - `name: string` + - `read_only: optional boolean` - The name 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. - - `type: "function_call"` + - `tool_names: optional array of string` - The type of the function tool call. Always `function_call`. + List of allowed tool names. - - `"function_call"` + - `never: optional object { read_only, tool_names }` - - `id: optional string` + A filter object to specify which tools are allowed. - The unique ID of the function tool call. + - `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. + - `McpToolApprovalSetting = "always" or "never"` - - `caller: optional object { type } or object { caller_id, type }` + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - The execution context that produced this tool call. + - `"always"` - - `Direct object { type }` + - `"never"` - - `type: "direct"` + - `server_description: optional string` - - `"direct"` + Optional description of the MCP server, used to provide more context. - - `Program object { caller_id, type }` + - `server_url: optional string` - - `caller_id: string` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - The call ID of the program item that produced this tool call. + - `tunnel_id: optional string` - - `type: "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. - - `"program"` + - `CodeInterpreter object { container, type, allowed_callers }` - - `namespace: optional string` + A tool that runs Python code to help generate a response to a prompt. - The namespace of the function to run. + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `status: optional "in_progress" or "completed" or "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. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `string` - - `"in_progress"` + The container ID. - - `"completed"` + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - - `"incomplete"` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `FunctionCallOutput object { call_id, output, type, 4 more }` + - `type: "auto"` - The output of a function tool call. + Always `auto`. - - `call_id: string` + - `"auto"` - The unique ID of the function tool call generated by the model. + - `file_ids: optional array of string` - - `output: string or BetaResponseFunctionCallOutputItemList` + An optional list of uploaded files to make available to your code. - Text, image, or file output of the function tool call. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `string` + The memory limit for the code interpreter container. - A JSON string of the output of the function tool call. + - `"1g"` - - `BetaResponseFunctionCallOutputItemList = array of BetaResponseFunctionCallOutputItem` + - `"4g"` - An array of content outputs (text, image, file) for the function tool call. + - `"16g"` - - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` + - `"64g"` - A text input to the model. + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `text: string` + Network access policy for the container. - The text input to the model. + - `BetaContainerNetworkPolicyDisabled object { type }` - - `type: "input_text"` + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - The type of the input item. Always `input_text`. + - `type: "code_interpreter"` - - `"input_text"` + The type of the code interpreter tool. Always `code_interpreter`. - - `prompt_cache_breakpoint: optional object { mode }` + - `"code_interpreter"` - Marks the exact end of a reusable 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"` - - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` + - `ProgrammaticToolCalling object { type }` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `type: "programmatic_tool_calling"` - - `type: "input_image"` + The type of the tool. Always `programmatic_tool_calling`. - The type of the input item. Always `input_image`. + - `"programmatic_tool_calling"` - - `"input_image"` + - `ImageGeneration object { type, action, background, 9 more }` - - `detail: optional "low" or "high" or "auto" or "original"` + A tool that generates images using the GPT image models. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `type: "image_generation"` - - `"low"` + The type of the image generation tool. Always `image_generation`. - - `"high"` + - `"image_generation"` - - `"auto"` + - `action: optional "generate" or "edit" or "auto"` - - `"original"` + Whether to generate a new image or edit an existing image. Default: `auto`. - - `file_id: optional string` + - `"generate"` - The ID of the file to be sent to the model. + - `"edit"` - - `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. + - `background: optional "transparent" or "opaque" or "auto"` - - `prompt_cache_breakpoint: optional object { mode }` + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `"transparent"` - - `mode: "explicit"` + - `"opaque"` - The breakpoint mode. Always `explicit`. + - `"auto"` - - `"explicit"` + - `input_fidelity: optional "high" or "low"` - - `BetaResponseInputFileContent object { type, detail, file_data, 4 more }` + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - A file input to the model. + - `"high"` - - `type: "input_file"` + - `"low"` - The type of the input item. Always `input_file`. + - `input_image_mask: optional object { file_id, image_url }` - - `"input_file"` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `detail: optional "auto" or "low" or "high"` + - `file_id: optional 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`. + File ID for the mask image. - - `"auto"` + - `image_url: optional string` - - `"low"` + Base64-encoded mask image. - - `"high"` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `file_data: optional string` + The image generation model to use. Default: `gpt-image-1`. - The base64-encoded data of the file to be sent to the model. + - `string` - - `file_id: optional string` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - The ID of the file to be sent to the model. + The image generation model to use. Default: `gpt-image-1`. - - `file_url: optional string` + - `"gpt-image-1"` - The URL of the file to be sent to the model. + - `"gpt-image-1-mini"` - - `filename: optional string` + - `"gpt-image-1.5"` - The name of the file to be sent to the model. + - `moderation: optional "auto" or "low"` - - `prompt_cache_breakpoint: optional object { mode }` + Moderation level for the generated image. Default: `auto`. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `"auto"` - - `mode: "explicit"` + - `"low"` - The breakpoint mode. Always `explicit`. + - `output_compression: optional number` - - `"explicit"` + Compression level for the output image. Default: 100. - - `type: "function_call_output"` + - `output_format: optional "png" or "webp" or "jpeg"` - The type of the function tool call output. Always `function_call_output`. + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `"function_call_output"` + - `"png"` - - `id: optional string` + - `"webp"` - The unique ID of the function tool call output. Populated when this item is returned via API. + - `"jpeg"` - - `agent: optional object { agent_name }` + - `partial_images: optional number` - The agent that produced this item. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `agent_name: string` + - `quality: optional "low" or "medium" or "high" or "auto"` - The canonical name of the agent that produced this item. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `caller: optional object { type } or object { caller_id, type }` + - `"low"` - The execution context that produced this tool call. + - `"medium"` - - `Direct object { type }` + - `"high"` - - `type: "direct"` + - `"auto"` - The caller type. Always `direct`. + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `"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`. - - `Program object { caller_id, type }` + - `string` - - `caller_id: string` + - `"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"` + - `"1024x1024"` - The caller type. Always `program`. + - `"1024x1536"` - - `"program"` + - `"1536x1024"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"auto"` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + - `LocalShell object { type }` - - `"in_progress"` + A tool that allows the model to execute shell commands in a local environment. - - `"completed"` + - `type: "local_shell"` - - `"incomplete"` + The type of the local shell tool. Always `local_shell`. - - `AgentMessage object { author, content, recipient, 3 more }` + - `"local_shell"` - A message routed between agents. + - `Shell object { type, allowed_callers, environment }` - - `author: string` + A tool that allows the model to execute shell commands. - The sending agent identity. + - `type: "shell"` - - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` + The type of the shell tool. Always `shell`. - Plaintext, image, or encrypted content sent between agents. + - `"shell"` - - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` + - `allowed_callers: optional array of "direct" or "programmatic"` - A text input to the model. + The tool invocation context(s). - - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` + - `"direct"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `"programmatic"` - - `EncryptedContent object { encrypted_content, type }` + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - - `encrypted_content: string` + - `BetaLocalEnvironment object { type, skills }` - Opaque encrypted content. + - `BetaContainerReference object { container_id, type }` - - `type: "encrypted_content"` + - `Custom object { name, type, allowed_callers, 3 more }` - The type of the input item. Always `encrypted_content`. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `"encrypted_content"` + - `name: string` - - `recipient: string` + The name of the custom tool, used to identify it in tool calls. - The destination agent identity. + - `type: "custom"` - - `type: "agent_message"` + The type of the custom tool. Always `custom`. - The item type. Always `agent_message`. + - `"custom"` - - `"agent_message"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `id: optional string` + The tool invocation context(s). - The unique ID of this agent message item. + - `"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` - - `MultiAgentCall object { action, arguments, call_id, 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 was executed. + 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 }` - - `arguments: string` + A grammar defined by the user. - The action arguments as a JSON string. + - `definition: string` - - `call_id: string` + The grammar definition. - The unique ID linking this call to its output. + - `syntax: "lark" or "regex"` - - `type: "multi_agent_call"` + The syntax of the grammar definition. One of `lark` or `regex`. - The item type. Always `multi_agent_call`. + - `"lark"` - - `"multi_agent_call"` + - `"regex"` - - `id: optional string` + - `type: "grammar"` - The unique ID of this multi-agent call. + Grammar format. Always `grammar`. - - `agent: optional object { agent_name }` + - `"grammar"` - The agent that produced this item. + - `Namespace object { description, name, tools, type }` - - `agent_name: string` + Groups function/custom tools under a shared namespace. - The canonical name of the agent that produced this item. + - `description: string` - - `MultiAgentCallOutput object { action, call_id, output, 3 more }` + A description of the namespace shown to the model. - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `name: string` - The multi-agent action that produced this result. + The namespace name used in tool calls (for example, `crm`). - - `"spawn_agent"` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - - `"interrupt_agent"` + The function/custom tools available inside this namespace. - - `"list_agents"` + - `Function object { name, type, allowed_callers, 5 more }` - - `"send_message"` + - `name: string` - - `"followup_task"` + - `type: "function"` - - `"wait_agent"` + - `"function"` - - `call_id: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The unique ID of the multi-agent call. + The tool invocation context(s). - - `output: array of object { text, type, annotations }` + - `"direct"` - Text output returned by the multi-agent action. + - `"programmatic"` - - `text: string` + - `defer_loading: optional boolean` - The text content. + Whether this function should be deferred and discovered via tool search. - - `type: "output_text"` + - `description: optional string` - The content type. Always `output_text`. + - `output_schema: optional map[unknown]` - - `"output_text"` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `annotations: optional array of object { file_id, filename, index, type } or array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` + - `parameters: optional unknown` - Citations associated with the text content. + - `strict: optional boolean` - - `array of object { file_id, filename, index, 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. - - `file_id: string` + - `Custom object { name, type, allowed_callers, 3 more }` - The ID of the file. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `filename: string` + - `name: string` - The filename of the file cited. + The name of the custom tool, used to identify it in tool calls. - - `index: number` + - `type: "custom"` - The index of the file in the list of files. + The type of the custom tool. Always `custom`. - - `type: "file_citation"` + - `"custom"` - The citation type. Always `file_citation`. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"file_citation"` + The tool invocation context(s). - - `array of object { end_index, start_index, title, 2 more }` + - `"direct"` - - `end_index: number` + - `"programmatic"` - The index of the last character of the citation in the message. + - `defer_loading: optional boolean` - - `start_index: number` + Whether this tool should be deferred and discovered via tool search. - The index of the first character of the citation in the message. + - `description: optional string` - - `title: string` + Optional description of the custom tool, used to provide more context. - The title of the cited resource. + - `format: optional object { type } or object { definition, syntax, type }` - - `type: "url_citation"` + The input format for the custom tool. Default is unconstrained text. - The citation type. Always `url_citation`. + - `Text object { type }` - - `"url_citation"` + Unconstrained free-form text. - - `url: string` + - `type: "text"` - The URL of the cited resource. + Unconstrained text format. Always `text`. - - `array of object { container_id, end_index, file_id, 3 more }` + - `"text"` - - `container_id: string` + - `Grammar object { definition, syntax, type }` - The ID of the container. + A grammar defined by the user. - - `end_index: number` + - `definition: string` - The index of the last character of the citation in the message. + The grammar definition. - - `file_id: string` + - `syntax: "lark" or "regex"` - The ID of the container file. + The syntax of the grammar definition. One of `lark` or `regex`. - - `filename: string` + - `"lark"` - The filename of the container file cited. + - `"regex"` - - `start_index: number` + - `type: "grammar"` - The index of the first character of the citation in the message. + Grammar format. Always `grammar`. - - `type: "container_file_citation"` + - `"grammar"` - The citation type. Always `container_file_citation`. + - `type: "namespace"` - - `"container_file_citation"` + The type of the tool. Always `namespace`. - - `type: "multi_agent_call_output"` + - `"namespace"` - The item type. Always `multi_agent_call_output`. + - `ToolSearch object { type, description, execution, parameters }` - - `"multi_agent_call_output"` + Hosted or BYOT tool search configuration for deferred tools. - - `id: optional string` + - `type: "tool_search"` - The unique ID of this multi-agent call output. + 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"` - - `ToolSearchCall object { arguments, type, id, 4 more }` + Whether tool search is executed by the server or by the client. - - `arguments: unknown` + - `"server"` - The arguments supplied to the tool search call. + - `"client"` - - `type: "tool_search_call"` + - `parameters: optional unknown` - The item type. Always `tool_search_call`. + Parameter schema for a client-executed tool search tool. - - `"tool_search_call"` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - - `id: optional string` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - The unique ID of this tool search call. + - `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"` - - `call_id: optional string` + - `"text"` - The unique ID of the tool search call generated by the model. + - `"image"` - - `execution: optional "server" or "client"` + - `search_context_size: optional "low" or "medium" or "high"` - Whether tool search was executed by the server or by the 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. - - `"server"` + - `"low"` - - `"client"` + - `"medium"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"high"` - The status of the tool search call. + - `user_location: optional object { type, city, country, 2 more }` - - `"in_progress"` + The user's location. - - `"completed"` + - `type: "approximate"` - - `"incomplete"` + The type of location approximation. Always `approximate`. - - `ToolSearchOutput object { tools, type, id, 4 more }` + - `"approximate"` - - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` + - `city: optional string` - The loaded tool definitions returned by the tool search output. + Free text input for the city of the user, e.g. `San Francisco`. - - `Function object { name, parameters, strict, 5 more }` + - `country: 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 two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `name: string` + - `region: optional string` - The name of the function to call. + Free text input for the region of the user, e.g. `California`. - - `parameters: map[unknown]` + - `timezone: optional string` - A JSON schema object describing the parameters of the function. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `strict: boolean` + - `ApplyPatch object { type, allowed_callers }` - Whether strict parameter validation is enforced for this function tool. + Allows the assistant to create, delete, or update files using unified diffs. - - `type: "function"` + - `type: "apply_patch"` - The type of the function tool. Always `function`. + The type of the tool. Always `apply_patch`. - - `"function"` + - `"apply_patch"` - `allowed_callers: optional array of "direct" or "programmatic"` @@ -190431,1183 +190293,1172 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"programmatic"` - - `defer_loading: optional boolean` + - `type: "additional_tools"` - Whether this function is deferred and loaded via tool search. + The type of the item. Always `additional_tools`. - - `description: optional string` + - `"additional_tools"` - 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](https://platform.openai.com/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](https://platform.openai.com/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](https://platform.openai.com/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. - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + - `path: string` - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + Path of the file to update. - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `type: "update_file"` - - `"transparent"` + Update an existing file with the provided diff. - - `"opaque"` + - `"update_file"` - - `"auto"` + - `status: "in_progress" or "completed"` - - `input_fidelity: optional "high" or "low"` + The status of the apply patch tool call. One of `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`. + - `"in_progress"` - - `"high"` + - `"completed"` - - `"low"` + - `type: "apply_patch_call"` - - `input_image_mask: optional object { file_id, image_url }` + The type of the item. Always `apply_patch_call`. - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `"apply_patch_call"` - - `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-2" or 3 more` + - `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. - - `string` + - `Direct object { type }` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `type: "direct"` - The image generation model to use. Default: `gpt-image-1`. + - `"direct"` - - `"gpt-image-1"` + - `Program object { caller_id, type }` - - `"gpt-image-1-mini"` + - `caller_id: string` - - `"gpt-image-2"` + The call ID of the program item that produced this tool call. - - `"gpt-image-2-2026-04-21"` + - `type: "program"` - - `"gpt-image-1.5"` + - `"program"` - - `"chatgpt-image-latest"` + - `created_by: optional string` - - `moderation: optional "auto" or "low"` + The ID of the entity that created this tool call. - Moderation level for the generated image. Default: `auto`. + - `ApplyPatchCallOutput object { id, call_id, status, 5 more }` - - `"auto"` + The output emitted by an apply patch tool call. - - `"low"` + - `id: string` - - `output_compression: optional number` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - Compression level for the output image. Default: 100. + - `call_id: string` - - `output_format: optional "png" or "webp" or "jpeg"` + The unique ID of the apply patch tool call generated by the model. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `status: "completed" or "failed"` - - `"png"` + The status of the apply patch tool call output. One of `completed` or `failed`. - - `"webp"` + - `"completed"` - - `"jpeg"` + - `"failed"` - - `partial_images: optional number` + - `type: "apply_patch_call_output"` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + The type of the item. Always `apply_patch_call_output`. - - `quality: optional "low" or "medium" or "high" or "auto"` + - `"apply_patch_call_output"` - 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"` + - `caller: optional object { type } or object { caller_id, type }` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + The execution context 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`. + - `Direct object { type }` - - `string` + - `type: "direct"` - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `"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`. + - `Program object { caller_id, type }` - - `"1024x1024"` + - `caller_id: string` - - `"1024x1536"` + The call ID of the program item that produced this tool call. - - `"1536x1024"` + - `type: "program"` - - `"auto"` + - `"program"` - - `LocalShell object { type }` + - `created_by: optional string` - A tool that allows the model to execute shell commands in a local environment. + The ID of the entity that created this tool call output. - - `type: "local_shell"` + - `output: optional string` - The type of the local shell tool. Always `local_shell`. + Optional textual output returned by the apply patch tool. - - `"local_shell"` + - `McpCall object { id, arguments, name, 7 more }` - - `Shell object { type, allowed_callers, environment }` + An invocation of a tool on an MCP server. - A tool that allows the model to execute shell commands. + - `id: string` - - `type: "shell"` + The unique ID of the tool call. - The type of the shell tool. Always `shell`. + - `arguments: string` - - `"shell"` + 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. - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + - `type: "mcp_call"` - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + The type of the item. Always `mcp_call`. - - `type: "container_auto"` + - `"mcp_call"` - 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"` + - `approval_request_id: optional string` - The memory limit for the container. + 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. - - `"1g"` + - `error: optional string` - - `"4g"` + The error from the tool call, if any. - - `"16g"` + - `output: optional string` - - `"64g"` + The output from the tool call. - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - Network access policy for the container. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `BetaContainerNetworkPolicyDisabled object { type }` + - `"in_progress"` - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `"completed"` - - `skills: optional array of BetaSkillReference or BetaInlineSkill` + - `"incomplete"` - An optional list of skills referenced by id or inline data. + - `"calling"` - - `BetaSkillReference object { skill_id, type, version }` + - `"failed"` - - `skill_id: string` + - `McpListTools object { id, server_label, tools, 3 more }` - The ID of the referenced skill. + A list of tools available on an MCP server. - - `type: "skill_reference"` + - `id: string` - References a skill created with the /v1/skills endpoint. + The unique ID of the list. - - `"skill_reference"` + - `server_label: string` - - `version: optional string` + The label of the MCP server. - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `tools: array of object { input_schema, name, annotations, description }` - - `BetaInlineSkill object { description, name, source, type }` + The tools available on the server. - - `description: string` + - `input_schema: unknown` - The description of the skill. + The JSON schema describing the tool's input. - `name: string` - The name of the skill. + The name of the tool. - - `source: BetaInlineSkillSource` + - `annotations: optional unknown` - Inline skill payload + Additional annotations about the tool. - - `data: string` + - `description: optional string` - Base64-encoded skill zip bundle. + The description of the tool. - - `media_type: "application/zip"` + - `type: "mcp_list_tools"` - The media type of the inline skill payload. Must be `application/zip`. + The type of the item. Always `mcp_list_tools`. - - `"application/zip"` + - `"mcp_list_tools"` - - `type: "base64"` + - `agent: optional object { agent_name }` - The type of the inline skill source. Must be `base64`. + The agent that produced this item. - - `"base64"` + - `agent_name: string` - - `type: "inline"` + The canonical name of the agent that produced this item. - Defines an inline skill for this request. + - `error: optional string` - - `"inline"` + Error message if the server could not list tools. - - `BetaLocalEnvironment object { type, skills }` + - `McpApprovalRequest object { id, arguments, name, 3 more }` - - `type: "local"` + A request for human approval of a tool invocation. - Use a local computer environment. + - `id: string` - - `"local"` + The unique ID of the approval request. - - `skills: optional array of BetaLocalSkill` + - `arguments: string` - An optional list of skills. + A JSON string of arguments for the tool. - - `description: string` + - `name: string` - The description of the skill. + The name of the tool to run. - - `name: string` + - `server_label: string` - The name of the skill. + The label of the MCP server making the request. - - `path: string` + - `type: "mcp_approval_request"` - The path to the directory containing the skill. + The type of the item. Always `mcp_approval_request`. - - `BetaContainerReference object { container_id, type }` + - `"mcp_approval_request"` - - `container_id: string` + - `agent: optional object { agent_name }` - The ID of the referenced container. + The agent that produced this item. - - `type: "container_reference"` + - `agent_name: string` - References a container created with the /v1/containers endpoint + The canonical name of the agent that produced this item. - - `"container_reference"` + - `McpApprovalResponse object { id, approval_request_id, approve, 3 more }` - - `Custom object { name, type, allowed_callers, 3 more }` + A response to an MCP approval request. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `id: string` - - `name: string` + The unique ID of the approval response - The name of the custom tool, used to identify it in tool calls. + - `approval_request_id: string` - - `type: "custom"` + The ID of the approval request being answered. - The type of the custom tool. Always `custom`. + - `approve: boolean` - - `"custom"` + Whether the request was approved. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `type: "mcp_approval_response"` - The tool invocation context(s). + The type of the item. Always `mcp_approval_response`. - - `"direct"` + - `"mcp_approval_response"` - - `"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. + - `reason: optional string` - - `format: optional object { type } or object { definition, syntax, type }` + Optional reason for the decision. - The input format for the custom tool. Default is unconstrained text. + - `CustomToolCall object { call_id, input, name, 5 more }` - - `Text object { type }` + A call to a custom tool created by the model. - Unconstrained free-form text. + - `call_id: string` - - `type: "text"` + An identifier used to map this custom tool call to a tool call output. - Unconstrained text format. Always `text`. + - `input: string` - - `"text"` + The input for the custom tool call generated by the model. - - `Grammar object { definition, syntax, type }` + - `name: string` - A grammar defined by the user. + The name of the custom tool being called. - - `definition: string` + - `type: "custom_tool_call"` - The grammar definition. + The type of the custom tool call. Always `custom_tool_call`. - - `syntax: "lark" or "regex"` + - `"custom_tool_call"` - The syntax of the grammar definition. One of `lark` or `regex`. + - `id: optional string` - - `"lark"` + The unique ID of the custom tool call in the OpenAI platform. - - `"regex"` + - `agent: optional object { agent_name }` - - `type: "grammar"` + The agent that produced this item. - Grammar format. Always `grammar`. + - `agent_name: string` - - `"grammar"` + The canonical name of the agent that produced this item. - - `Namespace object { description, name, tools, type }` + - `caller: optional object { type } or object { caller_id, type }` - Groups function/custom tools under a shared namespace. + The execution context that produced this tool call. - - `description: string` + - `Direct object { type }` - A description of the namespace shown to the model. + - `type: "direct"` - - `name: string` + - `"direct"` - The namespace name used in tool calls (for example, `crm`). + - `Program object { caller_id, type }` - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + - `caller_id: string` - The function/custom tools available inside this namespace. + The call ID of the program item that produced this tool call. - - `Function object { name, type, allowed_callers, 5 more }` + - `type: "program"` - - `name: string` + - `"program"` - - `type: "function"` + - `namespace: optional string` - - `"function"` + The namespace of the custom tool being called. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `CustomToolCallOutput object { id, call_id, output, 5 more }` - The tool invocation context(s). + - `id: string` - - `"direct"` + The unique ID of the custom tool call output item. - - `"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 should be deferred and discovered 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. - - `output_schema: optional map[unknown]` + - `StringOutput = string` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + A string of the output of the custom tool call. - - `parameters: optional unknown` + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `strict: optional boolean` + Text, image, or file output of the custom tool 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. + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `Custom object { name, type, allowed_callers, 3 more }` + A text input to the model. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/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. + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `type: "custom"` + A file input to the model. - The type of the custom tool. Always `custom`. + - `status: "in_progress" or "completed" or "incomplete"` - - `"custom"` + 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: "custom_tool_call_output"` - - `defer_loading: optional boolean` + The type of the custom tool call output. Always `custom_tool_call_output`. - Whether this tool should be deferred and discovered via tool search. + - `"custom_tool_call_output"` - - `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"` + The caller type. Always `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`. + The caller type. Always `program`. - - `"lark"` + - `"program"` - - `"regex"` + - `created_by: optional string` - - `type: "grammar"` + The identifier of the actor that created the item. - Grammar format. Always `grammar`. + - `parallel_tool_calls: boolean` - - `"grammar"` + Whether to allow the model to run tool calls in parallel. - - `type: "namespace"` + - `temperature: number` - The type of the tool. Always `namespace`. + 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. - - `"namespace"` + - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` - - `ToolSearch object { type, description, execution, parameters }` + 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. - Hosted or BYOT tool search configuration for deferred tools. + - `BetaToolChoiceOptions = "none" or "auto" or "required"` - - `type: "tool_search"` + Controls which (if any) tool is called by the model. - The type of the tool. Always `tool_search`. + `none` means the model will not call any tool and instead generates a message. - - `"tool_search"` + `auto` means the model can pick between generating a message or calling one or + more tools. - - `description: optional string` + `required` means the model must call one or more tools. - Description shown to the model for a client-executed tool search tool. + - `"none"` - - `execution: optional "server" or "client"` + - `"auto"` - Whether tool search is executed by the server or by the client. + - `"required"` - - `"server"` + - `BetaToolChoiceAllowed object { mode, tools, type }` - - `"client"` + Constrains the tools available to the model to a pre-defined set. - - `parameters: optional unknown` + - `mode: "auto" or "required"` - Parameter schema for a client-executed tool search tool. + Constrains the tools available to the model to a pre-defined set. - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + `auto` allows the model to pick from among the allowed tools and generate a + 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). + `required` requires the model to call one or more of the allowed tools. - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `"auto"` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `"required"` - - `"web_search_preview"` + - `tools: array of map[unknown]` - - `"web_search_preview_2025_03_11"` + A list of tool definitions that the model should be allowed to call. - - `search_content_types: optional array of "text" or "image"` + 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"` - - `search_context_size: optional "low" or "medium" or "high"` + Allowed tool configuration type. Always `allowed_tools`. - 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. + - `"allowed_tools"` - - `"low"` + - `BetaToolChoiceTypes object { type }` - - `"medium"` + 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). - - `"high"` + Allowed values are: - - `user_location: optional object { type, city, country, 2 more }` + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - The user's location. + - `"file_search"` - - `type: "approximate"` + - `"web_search_preview"` - The type of location approximation. Always `approximate`. + - `"computer"` - - `"approximate"` + - `"computer_use_preview"` - - `city: optional string` + - `"computer_use"` - Free text input for the city of the user, e.g. `San Francisco`. + - `"web_search_preview_2025_03_11"` - - `country: optional string` + - `"image_generation"` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `"code_interpreter"` - - `region: optional string` + - `BetaToolChoiceFunction object { name, type }` - Free text input for the region of the user, e.g. `California`. + Use this option to force the model to call a specific function. - - `timezone: optional string` + - `name: string` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The name of the function to call. - - `ApplyPatch object { type, allowed_callers }` + - `type: "function"` - Allows the assistant to create, delete, or update files using unified diffs. + For function calling, the type is always `function`. - - `type: "apply_patch"` + - `"function"` - The type of the tool. Always `apply_patch`. + - `BetaToolChoiceMcp object { server_label, type, name }` - - `"apply_patch"` + Use this option to force the model to call a specific tool on a remote MCP server. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `server_label: string` - The tool invocation context(s). + The label of the MCP server to use. - - `"direct"` + - `type: "mcp"` - - `"programmatic"` + For MCP tools, the type is always `mcp`. - - `type: "tool_search_output"` + - `"mcp"` - The item type. Always `tool_search_output`. + - `name: optional string` - - `"tool_search_output"` + The name of the tool to call on the server. - - `id: optional string` + - `BetaToolChoiceCustom object { name, type }` - The unique ID of this 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`. - - `call_id: optional string` + - `"custom"` - The unique ID of the tool search call generated by the model. + - `BetaSpecificProgrammaticToolCallingParam object { type }` - - `execution: optional "server" or "client"` + - `type: "programmatic_tool_calling"` - Whether tool search was executed by the server or by the client. + The tool to call. Always `programmatic_tool_calling`. - - `"server"` + - `"programmatic_tool_calling"` - - `"client"` + - `BetaToolChoiceApplyPatch object { type }` - - `status: optional "in_progress" or "completed" or "incomplete"` + Forces the model to call the apply_patch tool when executing a tool call. - The status of the tool search output. + - `type: "apply_patch"` - - `"in_progress"` + The tool to call. Always `apply_patch`. - - `"completed"` + - `"apply_patch"` - - `"incomplete"` + - `BetaToolChoiceShell object { type }` - - `AdditionalTools object { role, tools, type, 2 more }` + Forces the model to call the shell tool when a tool call is required. - - `role: "developer"` + - `type: "shell"` - The role that provided the additional tools. Only `developer` is supported. + The tool to call. Always `shell`. - - `"developer"` + - `"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` - A list of additional tools 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 }` @@ -191870,7 +191721,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-web-search). + [web search tool](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -191930,7 +191781,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -191982,7 +191833,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -192174,19 +192025,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `background: optional "transparent" or "opaque" or "auto"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. - - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. - - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - `"transparent"` @@ -192215,13 +192055,13 @@ curl -X POST https://api.openai.com/v1/responses/compact \ Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `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-2" or 3 more` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` The image generation model to use. Default: `gpt-image-1`. @@ -192229,14 +192069,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"gpt-image-1-mini"` - - `"gpt-image-2"` - - - `"gpt-image-2-2026-04-21"` - - `"gpt-image-1.5"` - - `"chatgpt-image-latest"` - - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -192333,7 +192167,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -192447,7 +192281,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -192615,2958 +192449,2244 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"programmatic"` - - `type: "additional_tools"` - - The item type. Always `additional_tools`. - - - `"additional_tools"` + - `top_p: number` - - `id: 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 unique ID of this additional tools item. + We generally recommend altering this or `temperature` but not both. - - `agent: optional object { agent_name }` + - `background: optional boolean` - The agent that produced this item. + Whether to run the model response in the background. + [Learn more](/docs/guides/background). - - `agent_name: string` + - `completed_at: optional number` - The canonical name of the agent that produced this item. + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - - `Reasoning object { id, summary, type, 4 more }` + - `conversation: optional object { id }` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + 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 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 - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. - - - `status: optional "in_progress" or "completed" or "incomplete"` - - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `Compaction object { encrypted_content, type, id, agent }` - - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/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. + The unique ID of the conversation that this response was associated with. - - `agent: optional object { agent_name }` + - `max_output_tokens: optional number` - The agent that produced this item. + 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). - - `agent_name: string` + - `max_tool_calls: optional number` - The canonical name of the agent that produced this item. + 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. - - `ImageGenerationCall object { id, result, status, 2 more }` + - `moderation: optional object { input, output }` - An image generation request made by the model. + Moderation results for the response input and output, if moderated completions were requested. - - `id: string` + - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` - The unique ID of the image generation call. + Moderation for the response input. - - `result: string` + - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` - The generated image encoded in base64. + A moderation result produced for the response input or output. - - `status: "in_progress" or "completed" or "generating" or "failed"` + - `categories: map[boolean]` - The status of the image generation call. + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `"in_progress"` + - `category_applied_input_types: map[array of "text" or "image"]` - - `"completed"` + Which modalities of input are reflected by the score for each category. - - `"generating"` + - `"text"` - - `"failed"` + - `"image"` - - `type: "image_generation_call"` + - `category_scores: map[number]` - The type of the image generation call. Always `image_generation_call`. + A dictionary of moderation categories to scores. - - `"image_generation_call"` + - `flagged: boolean` - - `agent: optional object { agent_name }` + A boolean indicating whether the content was flagged by any category. - The agent that produced this item. + - `model: string` - - `agent_name: string` + The moderation model that produced this result. - The canonical name of the agent that produced this item. + - `type: "moderation_result"` - - `CodeInterpreterCall object { id, code, container_id, 4 more }` + The object type, which was always `moderation_result` for successful moderation results. - A tool call to run code. + - `"moderation_result"` - - `id: string` + - `Error object { code, message, type }` - The unique ID of the code interpreter tool call. + An error produced while attempting moderation for the response input or output. - `code: string` - The code to run, or null if not available. - - - `container_id: string` + The error code. - The ID of the container used to run the code. + - `message: string` - - `outputs: array of object { logs, type } or object { type, url }` + The error message. - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `type: "error"` - - `Logs object { logs, type }` + The object type, which was always `error` for moderation failures. - The logs output from the code interpreter. + - `"error"` - - `logs: string` + - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` - The logs output from the code interpreter. + Moderation for the response output. - - `type: "logs"` + - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` - The type of the output. Always `logs`. + A moderation result produced for the response input or output. - - `"logs"` + - `categories: map[boolean]` - - `Image object { type, url }` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - The image output from the code interpreter. + - `category_applied_input_types: map[array of "text" or "image"]` - - `type: "image"` + Which modalities of input are reflected by the score for each category. - The type of the output. Always `image`. + - `"text"` - `"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. + - `category_scores: map[number]` - - `server_label: string` + A dictionary of moderation categories to scores. - The label of the MCP server. + - `flagged: boolean` - - `tools: array of object { input_schema, name, annotations, description }` + A boolean indicating whether the content was flagged by any category. - The tools available on the server. + - `model: string` - - `input_schema: unknown` + The moderation model that produced this result. - The JSON schema describing the tool's input. + - `type: "moderation_result"` - - `name: string` + The object type, which was always `moderation_result` for successful moderation results. - The name of the tool. + - `"moderation_result"` - - `annotations: optional unknown` + - `Error object { code, message, type }` - Additional annotations about the tool. + An error produced while attempting moderation for the response input or output. - - `description: optional string` + - `code: string` - The description of the tool. + The error code. - - `type: "mcp_list_tools"` + - `message: string` - The type of the item. Always `mcp_list_tools`. + The error message. - - `"mcp_list_tools"` + - `type: "error"` - - `agent: optional object { agent_name }` + The object type, which was always `error` for moderation failures. - The agent that produced this item. + - `"error"` - - `agent_name: string` + - `output_text: optional string` - The canonical name of the agent that produced this item. + 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. - - `error: optional string` + - `previous_response_id: optional string` - Error message if the server could not list tools. + 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`. - - `McpApprovalRequest object { id, arguments, name, 3 more }` + - `prompt: optional BetaResponsePrompt` - A request for human approval of a tool invocation. + Reference to a prompt template and its variables. + [Learn more](/docs/guides/text?api-mode=responses#reusable-prompts). - `id: string` - The unique ID of the 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`. + The unique identifier of the prompt template to use. - - `"mcp_approval_response"` + - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` - - `id: optional 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 unique ID of the approval response + - `string` - - `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). - - `reason: optional string` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - Optional reason for the decision. + A file input to the model. - - `McpCall object { id, arguments, name, 7 more }` + - `version: optional string` - An invocation of a tool on an MCP server. + Optional version of the prompt template. - - `id: string` + - `prompt_cache_key: optional string` - The unique ID of the tool 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). - - `arguments: string` + - `prompt_cache_options: optional object { mode, ttl }` - A JSON string of the arguments passed to the tool. + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - - `name: string` + - `mode: "implicit" or "explicit"` - The name of the tool that was run. + Whether implicit prompt-cache breakpoints were enabled. - - `server_label: string` + - `"implicit"` - The label of the MCP server running the tool. + - `"explicit"` - - `type: "mcp_call"` + - `ttl: "30m"` - The type of the item. Always `mcp_call`. + The minimum lifetime applied to each cache breakpoint. - - `"mcp_call"` + - `"30m"` - - `agent: optional object { agent_name }` + - `prompt_cache_retention: optional "in_memory" or "24h"` - The agent that produced this item. + Deprecated. Use `prompt_cache_options.ttl` instead. - - `agent_name: 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. - The canonical name of the agent that produced this item. + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - - `approval_request_id: optional string` + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + - `"in_memory"` - - `error: optional string` + - `"24h"` - The error from the tool call, if any. + - `reasoning: optional object { context, effort, generate_summary, 2 more }` - - `output: optional string` + **gpt-5 and o-series models only** - The output from the tool call. + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `context: optional "auto" or "current_turn" or "all_turns"` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + Controls which reasoning items are rendered back to the model on later turns. + When returned on a response, this is the effective reasoning context mode + used for the response. - - `"in_progress"` + - `"auto"` - - `"completed"` + - `"current_turn"` - - `"incomplete"` + - `"all_turns"` - - `"calling"` + - `effort: optional "none" or "minimal" or "low" or 4 more` - - `"failed"` + 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. - - `CustomToolCallOutput object { call_id, output, type, 3 more }` + - `"none"` - The output of a custom tool call from your code, being sent back to the model. + - `"minimal"` - - `call_id: string` + - `"low"` - The call ID, used to map this custom tool call output to a custom tool call. + - `"medium"` - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `"high"` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `"xhigh"` - - `StringOutput = string` + - `"max"` - A string of the output of the custom tool call. + - `generate_summary: optional "auto" or "concise" or "detailed"` - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + **Deprecated:** use `summary` instead. - Text, image, or file output of the custom tool 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`. - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `"auto"` - A text input to the model. + - `"concise"` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `"detailed"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `mode: optional string or "standard" or "pro"` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + Controls the reasoning execution mode for the request. - A file input to the model. + When returned on a response, this is the effective execution mode. - - `type: "custom_tool_call_output"` + - `string` - The type of the custom tool call output. Always `custom_tool_call_output`. + - `"standard" or "pro"` - - `"custom_tool_call_output"` + Controls the reasoning execution mode for the request. - - `id: optional string` + When returned on a response, this is the effective execution mode. - The unique ID of the custom tool call output in the OpenAI platform. + - `"standard"` - - `agent: optional object { agent_name }` + - `"pro"` - The agent that produced this item. + - `summary: optional "auto" or "concise" or "detailed"` - - `agent_name: 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 canonical name of the agent that produced this item. + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - - `caller: optional object { type } or object { caller_id, type }` + - `"auto"` - The execution context that produced this tool call. + - `"concise"` - - `Direct object { type }` + - `"detailed"` - - `type: "direct"` + - `safety_identifier: optional string` - The caller type. Always `direct`. + 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` - - `Program object { caller_id, type }` + Specifies the processing type used for serving the request. - - `caller_id: 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 call ID of the program item that produced this tool call. + 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: "program"` + - `"auto"` - The caller type. Always `program`. + - `"default"` - - `"program"` + - `"flex"` - - `CustomToolCall object { call_id, input, name, 5 more }` + - `"scale"` - A call to a custom tool created by the model. + - `"priority"` - - `call_id: string` + - `status: optional BetaResponseStatus` - An identifier used to map this custom tool call to a tool call output. + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - - `input: string` + - `"completed"` - The input for the custom tool call generated by the model. + - `"failed"` - - `name: string` + - `"in_progress"` - The name of the custom tool being called. + - `"cancelled"` - - `type: "custom_tool_call"` + - `"queued"` - The type of the custom tool call. Always `custom_tool_call`. + - `"incomplete"` - - `"custom_tool_call"` + - `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 custom tool call in the OpenAI platform. + - [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. - - `"direct"` + - `type: "text"` - - `Program object { caller_id, type }` + The type of response format being defined. Always `text`. - - `caller_id: string` + - `"text"` - The call ID of the program item that produced this tool call. + - `BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` - - `type: "program"` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - - `"program"` + - `name: string` - - `namespace: 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 namespace of the custom tool being called. + - `schema: map[unknown]` - - `CompactionTrigger object { type, agent }` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - Compacts the current context. Must be the final input item. + - `type: "json_schema"` - - `type: "compaction_trigger"` + The type of response format being defined. Always `json_schema`. - The type of the item. Always `compaction_trigger`. + - `"json_schema"` - - `"compaction_trigger"` + - `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 }` - - `ItemReference object { id, agent, 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. - An internal identifier for an item to reference. + - `type: "json_object"` - - `id: string` + The type of response format being defined. Always `json_object`. - The ID of the item to reference. + - `"json_object"` - - `agent: optional object { agent_name }` + - `verbosity: optional "low" or "medium" or "high"` - The agent that produced this item. + 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`. - - `agent_name: string` + - `"low"` - The canonical name of the agent that produced this item. + - `"medium"` - - `type: optional "item_reference"` + - `"high"` - The type of item to reference. Always `item_reference`. + - `top_logprobs: optional number` - - `"item_reference"` + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. - - `Program object { id, call_id, code, 3 more }` + - `truncation: optional "auto" or "disabled"` - - `id: string` + The truncation strategy to use for the model response. - The unique ID of this program 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. - - `call_id: string` + - `"auto"` - The stable call ID of the program item. + - `"disabled"` - - `code: string` + - `usage: optional BetaResponseUsage` - The JavaScript source executed by programmatic tool calling. + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - - `fingerprint: string` + - `input_tokens: number` - Opaque program replay fingerprint that must be round-tripped. + The number of input tokens. - - `type: "program"` + - `input_tokens_details: object { cache_write_tokens, cached_tokens }` - The item type. Always `program`. + A detailed breakdown of the input tokens. - - `"program"` + - `cache_write_tokens: number` - - `agent: optional object { agent_name }` + The number of input tokens that were written to the cache. - The agent that produced this item. + - `cached_tokens: number` - - `agent_name: string` + The number of tokens that were retrieved from the cache. + [More on prompt caching](/docs/guides/prompt-caching). - The canonical name of the agent that produced this item. + - `output_tokens: number` - - `ProgramOutput object { id, call_id, result, 3 more }` + The number of output tokens. - - `id: string` + - `output_tokens_details: object { reasoning_tokens }` - The unique ID of this program output item. + A detailed breakdown of the output tokens. - - `call_id: string` + - `reasoning_tokens: number` - The call ID of the program item. + The number of reasoning tokens. - - `result: string` + - `total_tokens: number` - The result produced by the program item. + The total number of tokens used. - - `status: "completed" or "incomplete"` + - `user: optional string` - The terminal status of the program output. + 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). - - `"completed"` + - `sequence_number: number` - - `"incomplete"` + The sequence number for this event. - - `type: "program_output"` + - `type: "response.completed"` - The item type. Always `program_output`. + The type of the event. Always `response.completed`. - - `"program_output"` + - `"response.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. - - `instructions: optional string` + - `BetaResponseContentPartAddedEvent object { content_index, item_id, output_index, 4 more }` - A system (or developer) message inserted into the model's context. + Emitted when a new content part is added. - 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. + - `content_index: number` - - `max_output_tokens: optional number` + The index of the content part that was added. - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + - `item_id: string` - - `max_tool_calls: optional number` + The ID of the output item that the content part was added to. - 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. + - `output_index: number` - - `metadata: optional map[string]` + The index of the output item that the content part was added 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. + - `part: BetaResponseOutputText or BetaResponseOutputRefusal or object { text, type }` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The content part that was added. - - `model: optional "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` + - `BetaResponseOutputText object { annotations, logprobs, text, 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](https://platform.openai.com/docs/models) - to browse and compare available models. + A text output from the model. - - `"gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more` + - `BetaResponseOutputRefusal object { refusal, 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](https://platform.openai.com/docs/models) - to browse and compare available models. + A refusal from the model. - - `"gpt-5.6-sol"` + - `ReasoningText object { text, type }` - - `"gpt-5.6-terra"` + Reasoning text from the model. - - `"gpt-5.6-luna"` + - `text: string` - - `"gpt-5.4"` + The reasoning text from the model. - - `"gpt-5.4-mini"` + - `type: "reasoning_text"` - - `"gpt-5.4-nano"` + The type of the reasoning text. Always `reasoning_text`. - - `"gpt-5.4-mini-2026-03-17"` + - `"reasoning_text"` - - `"gpt-5.4-nano-2026-03-17"` + - `sequence_number: number` - - `"gpt-5.3-chat-latest"` + The sequence number of this event. - - `"gpt-5.2"` + - `type: "response.content_part.added"` - - `"gpt-5.2-2025-12-11"` + The type of the event. Always `response.content_part.added`. - - `"gpt-5.2-chat-latest"` + - `"response.content_part.added"` - - `"gpt-5.2-pro"` + - `agent: optional object { agent_name }` - - `"gpt-5.2-pro-2025-12-11"` + The agent that owns this multi-agent streaming event. - - `"gpt-5.1"` + - `agent_name: string` - - `"gpt-5.1-2025-11-13"` + The canonical name of the agent that produced this item. - - `"gpt-5.1-codex"` + - `BetaResponseContentPartDoneEvent object { content_index, item_id, output_index, 4 more }` - - `"gpt-5.1-mini"` + Emitted when a content part is done. - - `"gpt-5.1-chat-latest"` + - `content_index: number` - - `"gpt-5"` + The index of the content part that is done. - - `"gpt-5-mini"` + - `item_id: string` - - `"gpt-5-nano"` + The ID of the output item that the content part was added to. - - `"gpt-5-2025-08-07"` + - `output_index: number` - - `"gpt-5-mini-2025-08-07"` + The index of the output item that the content part was added to. - - `"gpt-5-nano-2025-08-07"` + - `part: BetaResponseOutputText or BetaResponseOutputRefusal or object { text, type }` - - `"gpt-5-chat-latest"` + The content part that is done. - - `"gpt-4.1"` + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - - `"gpt-4.1-mini"` + A text output from the model. - - `"gpt-4.1-nano"` + - `BetaResponseOutputRefusal object { refusal, type }` - - `"gpt-4.1-2025-04-14"` + A refusal from the model. - - `"gpt-4.1-mini-2025-04-14"` + - `ReasoningText object { text, type }` - - `"gpt-4.1-nano-2025-04-14"` + Reasoning text from the model. - - `"o4-mini"` + - `text: string` - - `"o4-mini-2025-04-16"` + The reasoning text from the model. - - `"o3"` + - `type: "reasoning_text"` - - `"o3-2025-04-16"` + The type of the reasoning text. Always `reasoning_text`. - - `"o3-mini"` + - `"reasoning_text"` - - `"o3-mini-2025-01-31"` + - `sequence_number: number` - - `"o1"` + The sequence number of this event. - - `"o1-2024-12-17"` + - `type: "response.content_part.done"` - - `"o1-preview"` + The type of the event. Always `response.content_part.done`. - - `"o1-preview-2024-09-12"` + - `"response.content_part.done"` - - `"o1-mini"` + - `agent: optional object { agent_name }` - - `"o1-mini-2024-09-12"` + The agent that owns this multi-agent streaming event. - - `"gpt-4o"` + - `agent_name: string` - - `"gpt-4o-2024-11-20"` + The canonical name of the agent that produced this item. - - `"gpt-4o-2024-08-06"` + - `BetaResponseCreatedEvent object { response, sequence_number, type, agent }` - - `"gpt-4o-2024-05-13"` + An event that is emitted when a response is created. - - `"gpt-4o-audio-preview"` + - `response: BetaResponse` - - `"gpt-4o-audio-preview-2024-10-01"` + The response that was created. - - `"gpt-4o-audio-preview-2024-12-17"` + - `sequence_number: number` - - `"gpt-4o-audio-preview-2025-06-03"` + The sequence number for this event. - - `"gpt-4o-mini-audio-preview"` + - `type: "response.created"` - - `"gpt-4o-mini-audio-preview-2024-12-17"` + The type of the event. Always `response.created`. - - `"gpt-4o-search-preview"` + - `"response.created"` - - `"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"` + - `BetaResponseErrorEvent object { code, message, param, 3 more }` - - `"gpt-4o-mini"` + Emitted when an error occurs. - - `"gpt-4o-mini-2024-07-18"` + - `code: string` - - `"gpt-4-turbo"` + The error code. - - `"gpt-4-turbo-2024-04-09"` + - `message: string` - - `"gpt-4-0125-preview"` + The error message. - - `"gpt-4-turbo-preview"` + - `param: string` - - `"gpt-4-1106-preview"` + The error parameter. - - `"gpt-4-vision-preview"` + - `sequence_number: number` - - `"gpt-4"` + The sequence number of this event. - - `"gpt-4-0314"` + - `type: "error"` - - `"gpt-4-0613"` + The type of the event. Always `error`. - - `"gpt-4-32k"` + - `"error"` - - `"gpt-4-32k-0314"` + - `agent: optional object { agent_name }` - - `"gpt-4-32k-0613"` + The agent that owns this multi-agent streaming event. - - `"gpt-3.5-turbo"` + - `agent_name: string` - - `"gpt-3.5-turbo-16k"` + The canonical name of the agent that produced this item. - - `"gpt-3.5-turbo-0301"` + - `BetaResponseFileSearchCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` - - `"gpt-3.5-turbo-0613"` + Emitted when a file search call is completed (results found). - - `"gpt-3.5-turbo-1106"` + - `item_id: string` - - `"gpt-3.5-turbo-0125"` + The ID of the output item that the file search call is initiated. - - `"gpt-3.5-turbo-16k-0613"` + - `output_index: number` - - `"o1-pro"` + The index of the output item that the file search call is initiated. - - `"o1-pro-2025-03-19"` + - `sequence_number: number` - - `"o3-pro"` + The sequence number of this event. - - `"o3-pro-2025-06-10"` + - `type: "response.file_search_call.completed"` - - `"o3-deep-research"` + The type of the event. Always `response.file_search_call.completed`. - - `"o3-deep-research-2025-06-26"` + - `"response.file_search_call.completed"` - - `"o4-mini-deep-research"` + - `agent: optional object { agent_name }` - - `"o4-mini-deep-research-2025-06-26"` + The agent that owns this multi-agent streaming event. - - `"computer-use-preview"` + - `agent_name: string` - - `"computer-use-preview-2025-03-11"` + The canonical name of the agent that produced this item. - - `"gpt-5-codex"` + - `BetaResponseFileSearchCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` - - `"gpt-5-pro"` + Emitted when a file search call is initiated. - - `"gpt-5-pro-2025-10-06"` + - `item_id: string` - - `"gpt-5.1-codex-max"` + The ID of the output item that the file search call is initiated. - - `string` + - `output_index: number` - - `moderation: optional object { model, policy }` + The index of the output item that the file search call is initiated. - Configuration for running moderation on the input and output of this response. + - `sequence_number: number` - - `model: string` + The sequence number of this event. - The moderation model to use for moderated completions, e.g. 'omni-moderation-latest'. + - `type: "response.file_search_call.in_progress"` - - `policy: optional object { input, output }` + The type of the event. Always `response.file_search_call.in_progress`. - The policy to apply to moderated response input and output. + - `"response.file_search_call.in_progress"` - - `input: optional object { mode }` + - `agent: optional object { agent_name }` - The moderation policy for the response input. + The agent that owns this multi-agent streaming event. - - `mode: "score" or "block"` + - `agent_name: string` - - `"score"` + The canonical name of the agent that produced this item. - - `"block"` + - `BetaResponseFileSearchCallSearchingEvent object { item_id, output_index, sequence_number, 2 more }` - - `output: optional object { mode }` + Emitted when a file search is currently searching. - The moderation policy for the response output. + - `item_id: string` - - `mode: "score" or "block"` + The ID of the output item that the file search call is initiated. - - `"score"` + - `output_index: number` - - `"block"` + The index of the output item that the file search call is searching. - - `multi_agent: optional object { enabled, max_concurrent_subagents }` + - `sequence_number: number` - Configuration for server-hosted multi-agent execution. + The sequence number of this event. - - `enabled: boolean` + - `type: "response.file_search_call.searching"` - Whether to enable server-hosted multi-agent execution for this response. + The type of the event. Always `response.file_search_call.searching`. - - `max_concurrent_subagents: optional number` + - `"response.file_search_call.searching"` - `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. + - `agent: optional object { agent_name }` - - `parallel_tool_calls: optional boolean` + The agent that owns this multi-agent streaming event. - Whether to allow the model to run tool calls in parallel. + - `agent_name: string` - - `previous_response_id: optional string` + The canonical name of the agent that produced this item. - The unique ID of the previous response to the model. Use this to - create multi-turn conversations. Learn more about - [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + - `BetaResponseFunctionCallArgumentsDeltaEvent object { delta, item_id, output_index, 3 more }` - - `prompt: optional BetaResponsePrompt` + Emitted when there is a partial function-call arguments delta. - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + - `delta: string` - - `id: string` + The function-call arguments delta that is added. - The unique identifier of the prompt template to use. + - `item_id: string` - - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` + The ID of the output item that the function-call arguments delta is added to. - 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. + - `output_index: number` - - `string` + The index of the output item that the function-call arguments delta is added to. - - `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.function_call_arguments.delta"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The type of the event. Always `response.function_call_arguments.delta`. - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `"response.function_call_arguments.delta"` - A file input to the model. + - `agent: optional object { agent_name }` - - `version: optional string` + The agent that owns this multi-agent streaming event. - 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](https://platform.openai.com/docs/guides/prompt-caching). + - `BetaResponseFunctionCallArgumentsDoneEvent object { arguments, item_id, name, 4 more }` - - `prompt_cache_options: optional object { mode, ttl }` + Emitted when function-call arguments are finalized. - 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](https://platform.openai.com/docs/guides/prompt-caching) for current details. + - `arguments: string` - - `mode: optional "implicit" or "explicit"` + The function-call arguments. - 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. + - `item_id: string` - - `"implicit"` + The ID of the item. - - `"explicit"` + - `name: string` - - `ttl: optional "30m"` + The name of the function that was called. - 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. + - `output_index: number` - - `"30m"` + The index of the output item. - - `prompt_cache_retention: optional "in_memory" or "24h"` + - `sequence_number: number` - Deprecated. Use `prompt_cache_options.ttl` instead. + The sequence number of this event. - 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](https://platform.openai.com/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: "response.function_call_arguments.done"` - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + - `"response.function_call_arguments.done"` - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `agent: optional object { agent_name }` - - `"in_memory"` + The agent that owns this multi-agent streaming event. - - `"24h"` + - `agent_name: string` - - `reasoning: optional object { context, effort, generate_summary, 2 more }` + The canonical name of the agent that produced this item. - **gpt-5 and o-series models only** + - `BetaResponseInProgressEvent object { response, sequence_number, type, agent }` - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + Emitted when the response is in progress. - - `context: optional "auto" or "current_turn" or "all_turns"` + - `response: BetaResponse` - Controls which reasoning items are rendered back to the model on later turns. - When returned on a response, this is the effective reasoning context mode - used for the response. + The response that is in progress. - - `"auto"` + - `sequence_number: number` - - `"current_turn"` + The sequence number of this event. - - `"all_turns"` + - `type: "response.in_progress"` - - `effort: optional "none" or "minimal" or "low" or 4 more` + The type of the event. Always `response.in_progress`. - 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. + - `"response.in_progress"` - - `"none"` + - `agent: optional object { agent_name }` - - `"minimal"` + The agent that owns this multi-agent streaming event. - - `"low"` + - `agent_name: string` - - `"medium"` + The canonical name of the agent that produced this item. - - `"high"` + - `BetaResponseFailedEvent object { response, sequence_number, type, agent }` - - `"xhigh"` + An event that is emitted when a response fails. - - `"max"` + - `response: BetaResponse` - - `generate_summary: optional "auto" or "concise" or "detailed"` + The response that failed. - **Deprecated:** use `summary` instead. + - `sequence_number: 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 sequence number of this event. - - `"auto"` + - `type: "response.failed"` - - `"concise"` + The type of the event. Always `response.failed`. - - `"detailed"` + - `"response.failed"` - - `mode: optional string or "standard" or "pro"` + - `agent: optional object { agent_name }` - Controls the reasoning execution mode for the request. + The agent that owns this multi-agent streaming event. - When returned on a response, this is the effective execution mode. + - `agent_name: string` - - `string` + The canonical name of the agent that produced this item. - - `"standard" or "pro"` + - `BetaResponseIncompleteEvent object { response, sequence_number, type, agent }` - Controls the reasoning execution mode for the request. + An event that is emitted when a response finishes as incomplete. - When returned on a response, this is the effective execution mode. + - `response: BetaResponse` - - `"standard"` + The response that was incomplete. - - `"pro"` + - `sequence_number: number` - - `summary: optional "auto" or "concise" or "detailed"` + The sequence number of this event. - 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: "response.incomplete"` - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + The type of the event. Always `response.incomplete`. - - `"auto"` + - `"response.incomplete"` - - `"concise"` + - `agent: optional object { agent_name }` - - `"detailed"` + The agent that owns this multi-agent streaming event. - - `safety_identifier: optional string` + - `agent_name: 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](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + The canonical name of the agent that produced this item. - - `service_tier: optional "auto" or "default" or "flex" or 2 more` + - `BetaResponseOutputItemAddedEvent object { item, output_index, sequence_number, 2 more }` - Specifies the processing type used for serving the request. + Emitted when a new output item is added. - - 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](https://platform.openai.com/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'. + - `item: BetaResponseOutputItem` - 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 output item that was added. - - `"auto"` + - `BetaResponseOutputMessage object { id, content, role, 4 more }` - - `"default"` + An output message from the model. - - `"flex"` + - `FileSearchCall object { id, queries, status, 3 more }` - - `"scale"` + The results of a file search tool call. See the + [file search guide](/docs/guides/tools-file-search) for more information. - - `"priority"` + - `FunctionCall object { arguments, call_id, name, 6 more }` - - `store: optional boolean` + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. - Whether to store the generated model response for later retrieval via - API. + - `FunctionCallOutput object { id, call_id, output, 5 more }` - - `stream: optional boolean` + - `AgentMessage object { id, author, content, 3 more }` - 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](https://platform.openai.com/docs/api-reference/responses-streaming) - for more information. + - `MultiAgentCall object { id, action, arguments, 3 more }` - - `stream_options: optional object { include_obfuscation }` + - `MultiAgentCallOutput object { id, action, call_id, 3 more }` - Options for streaming responses. Only set this when you set `stream: true`. + - `WebSearchCall object { id, action, status, 2 more }` - - `include_obfuscation: optional boolean` + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. - When true, stream obfuscation will be enabled. Stream obfuscation adds - random characters to an `obfuscation` field on streaming delta events to - normalize payload sizes as a mitigation to certain side-channel attacks. - These obfuscation fields are included by default, but add a small amount - of overhead to the data stream. You can set `include_obfuscation` to - false to optimize for bandwidth if you trust the network links between - your application and the OpenAI API. + - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` - - `temperature: optional number` + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - 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. + - `ComputerCallOutput object { id, call_id, output, 5 more }` - - `text: optional BetaResponseTextConfig` + - `Reasoning object { id, summary, type, 4 more }` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn 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). - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `Program object { id, call_id, code, 3 more }` - - `format: optional BetaResponseFormatTextConfig` + - `ProgramOutput object { id, call_id, result, 3 more }` - An object specifying the format that the model must output. + - `ToolSearchCall object { id, arguments, call_id, 5 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](https://platform.openai.com/docs/guides/structured-outputs). + - `ToolSearchOutput object { id, call_id, execution, 5 more }` - The default format is `{ "type": "text" }` with no additional options. + - `AdditionalTools object { id, role, tools, 2 more }` - **Not recommended for gpt-4o and newer models:** + - `Compaction object { id, encrypted_content, type, 2 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 compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). - - `Text object { type }` + - `ImageGenerationCall object { id, result, status, 2 more }` - Default response format. Used to generate text responses. + An image generation request made by the model. - - `type: "text"` + - `CodeInterpreterCall object { id, code, container_id, 4 more }` - The type of response format being defined. Always `text`. + A tool call to run code. - - `"text"` + - `LocalShellCall object { id, action, call_id, 3 more }` - - `BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` + A tool call to run a command on the local shell. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `LocalShellCallOutput object { id, output, type, 2 more }` - - `name: string` + The output of a local shell tool call. - 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. + - `ShellCall object { id, action, call_id, 6 more }` - - `schema: map[unknown]` + A tool call that executes one or more shell commands in a managed environment. - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `ShellCallOutput object { id, call_id, max_output_length, 6 more }` - - `type: "json_schema"` + The output of a shell tool call that was emitted. - The type of response format being defined. Always `json_schema`. + - `ApplyPatchCall object { id, call_id, operation, 5 more }` - - `"json_schema"` + A tool call that applies file diffs by creating, deleting, or updating files. - - `description: optional string` + - `ApplyPatchCallOutput object { id, call_id, status, 5 more }` - A description of what the response format is for, used by the model to - determine how to respond in the format. + The output emitted by an apply patch tool call. - - `strict: optional boolean` + - `McpCall object { id, arguments, name, 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](https://platform.openai.com/docs/guides/structured-outputs). + An invocation of a tool on an MCP server. - - `JSONObject object { type }` + - `McpListTools object { id, server_label, tools, 3 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. + A list of tools available on an MCP server. - - `type: "json_object"` + - `McpApprovalRequest object { id, arguments, name, 3 more }` - The type of response format being defined. Always `json_object`. + A request for human approval of a tool invocation. - - `"json_object"` + - `McpApprovalResponse object { id, approval_request_id, approve, 3 more }` - - `verbosity: optional "low" or "medium" or "high"` + A response to an MCP approval request. - 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`. + - `CustomToolCall object { call_id, input, name, 5 more }` - - `"low"` + A call to a custom tool created by the model. - - `"medium"` + - `CustomToolCallOutput object { id, call_id, output, 5 more }` - - `"high"` + - `output_index: number` - - `tool_choice: optional BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` + The index of the output item that was added. - 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. + - `sequence_number: number` - - `BetaToolChoiceOptions = "none" or "auto" or "required"` + The sequence number of this event. - Controls which (if any) tool is called by the model. + - `type: "response.output_item.added"` - `none` means the model will not call any tool and instead generates a message. + The type of the event. Always `response.output_item.added`. - `auto` means the model can pick between generating a message or calling one or - more tools. + - `"response.output_item.added"` - `required` means the model must call one or more tools. + - `agent: optional object { agent_name }` - - `"none"` + The agent that owns this multi-agent streaming event. - - `"auto"` + - `agent_name: string` - - `"required"` + The canonical name of the agent that produced this item. - - `BetaToolChoiceAllowed object { mode, tools, type }` + - `BetaResponseOutputItemDoneEvent object { item, output_index, sequence_number, 2 more }` - Constrains the tools available to the model to a pre-defined set. + Emitted when an output item is marked done. - - `mode: "auto" or "required"` + - `item: BetaResponseOutputItem` - Constrains the tools available to the model to a pre-defined set. + The output item that was marked done. - `auto` allows the model to pick from among the allowed tools and generate a - message. + - `output_index: number` - `required` requires the model to call one or more of the allowed tools. + The index of the output item that was marked done. - - `"auto"` + - `sequence_number: number` - - `"required"` + The sequence number of this event. - - `tools: array of map[unknown]` + - `type: "response.output_item.done"` - A list of tool definitions that the model should be allowed to call. + The type of the event. Always `response.output_item.done`. - For the Responses API, the list of tool definitions might look like: + - `"response.output_item.done"` - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + - `agent: optional object { agent_name }` - - `type: "allowed_tools"` + The agent that owns this multi-agent streaming event. - Allowed tool configuration type. Always `allowed_tools`. + - `agent_name: string` - - `"allowed_tools"` + The canonical name of the agent that produced this item. - - `BetaToolChoiceTypes object { type }` + - `BetaResponseReasoningSummaryPartAddedEvent object { item_id, output_index, part, 4 more }` - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + Emitted when a new reasoning summary part is added. - - `type: "file_search" or "web_search_preview" or "computer" or 5 more` + - `item_id: string` - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + The ID of the item this summary part is associated with. - Allowed values are: + - `output_index: number` - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + The index of the output item this summary part is associated with. - - `"file_search"` + - `part: object { text, type }` - - `"web_search_preview"` + The summary part that was added. - - `"computer"` + - `text: string` - - `"computer_use_preview"` + The text of the summary part. - - `"computer_use"` + - `type: "summary_text"` - - `"web_search_preview_2025_03_11"` + The type of the summary part. Always `summary_text`. - - `"image_generation"` + - `"summary_text"` - - `"code_interpreter"` + - `sequence_number: number` - - `BetaToolChoiceFunction object { name, type }` + The sequence number of this event. - Use this option to force the model to call a specific function. + - `summary_index: number` - - `name: string` + The index of the summary part within the reasoning summary. - The name of the function to call. + - `type: "response.reasoning_summary_part.added"` - - `type: "function"` + The type of the event. Always `response.reasoning_summary_part.added`. - For function calling, the type is always `function`. + - `"response.reasoning_summary_part.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. + - `BetaResponseReasoningSummaryPartDoneEvent object { item_id, output_index, part, 5 more }` - - `type: "mcp"` + Emitted when a reasoning summary part is completed. - For MCP tools, the type is always `mcp`. + - `item_id: string` - - `"mcp"` + The ID of the item this summary part is associated with. - - `name: optional string` + - `output_index: number` - The name of the tool to call on the server. + The index of the output item this summary part is associated with. - - `BetaToolChoiceCustom object { name, type }` + - `part: object { text, type }` - Use this option to force the model to call a specific custom tool. + The completed summary part. - - `name: string` + - `text: string` - The name of the custom tool to call. + The text of the summary part. - - `type: "custom"` + - `type: "summary_text"` - For custom tool calling, the type is always `custom`. + The type of the summary part. Always `summary_text`. - - `"custom"` + - `"summary_text"` - - `BetaSpecificProgrammaticToolCallingParam object { type }` + - `sequence_number: number` - - `type: "programmatic_tool_calling"` + The sequence number of this event. - The tool to call. Always `programmatic_tool_calling`. + - `summary_index: number` - - `"programmatic_tool_calling"` + The index of the summary part within the reasoning summary. - - `BetaToolChoiceApplyPatch object { type }` + - `type: "response.reasoning_summary_part.done"` - Forces the model to call the apply_patch tool when executing a tool call. + The type of the event. Always `response.reasoning_summary_part.done`. - - `type: "apply_patch"` + - `"response.reasoning_summary_part.done"` - The tool to call. Always `apply_patch`. + - `agent: optional object { agent_name }` - - `"apply_patch"` + The agent that owns this multi-agent streaming event. - - `BetaToolChoiceShell object { type }` + - `agent_name: string` - Forces the model to call the shell tool when a tool call is required. + The canonical name of the agent that produced this item. - - `type: "shell"` + - `status: optional "incomplete"` - The tool to call. Always `shell`. + The completion status of the summary part. Omitted when the part completed + normally and set to `incomplete` when generation was interrupted. - - `"shell"` + - `"incomplete"` - - `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` + - `BetaResponseReasoningSummaryTextDeltaEvent object { delta, item_id, output_index, 4 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. + Emitted when a delta is added to a reasoning summary text. - We support the following categories of tools: + - `delta: string` - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/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](https://platform.openai.com/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](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. + The text delta that was added to the summary. - - `Function object { name, parameters, strict, 5 more }` + - `item_id: string` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + The ID of the item this summary text delta is associated with. - - `name: string` + - `output_index: number` - The name of the function to call. + The index of the output item this summary text delta is associated with. - - `parameters: map[unknown]` + - `sequence_number: number` - A JSON schema object describing the parameters of the function. + The sequence number of this event. - - `strict: boolean` + - `summary_index: number` - Whether strict parameter validation is enforced for this function tool. + The index of the summary part within the reasoning summary. + + - `type: "response.reasoning_summary_text.delta"` + + The type of the event. Always `response.reasoning_summary_text.delta`. + + - `"response.reasoning_summary_text.delta"` + + - `agent: optional object { agent_name }` - - `type: "function"` + The agent that owns this multi-agent streaming event. - The type of the function tool. Always `function`. + - `agent_name: string` - - `"function"` + The canonical name of the agent that produced this item. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `BetaResponseReasoningSummaryTextDoneEvent object { item_id, output_index, sequence_number, 4 more }` - The tool invocation context(s). + Emitted when a reasoning summary text is completed. - - `"direct"` + - `item_id: string` - - `"programmatic"` + The ID of the item this summary text is associated with. - - `defer_loading: optional boolean` + - `output_index: number` - Whether this function is deferred and loaded via tool search. + The index of the output item this summary text is associated with. - - `description: optional string` + - `sequence_number: number` - A description of the function. Used by the model to determine whether or not to call the function. + The sequence number of this event. - - `output_schema: optional map[unknown]` + - `summary_index: number` - A JSON schema object describing the JSON value encoded in string outputs for this function. + The index of the summary part within the reasoning summary. - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + - `text: string` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + The full text of the completed reasoning summary. - - `type: "file_search"` + - `type: "response.reasoning_summary_text.done"` - The type of the file search tool. Always `file_search`. + The type of the event. Always `response.reasoning_summary_text.done`. - - `"file_search"` + - `"response.reasoning_summary_text.done"` - - `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 }` + - `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. - - `CompoundFilter object { filters, type }` + - `item_id: string` - Combine multiple filters using `and` or `or`. + The ID of the item this reasoning text is associated with. - - `filters: array of object { key, type, value } or unknown` + - `output_index: number` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + The index of the output item this reasoning text is associated with. - - `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` + - `text: string` - The key to compare against the value. + The full text of the completed reasoning content. - - `type: "eq" or "ne" or "gt" or 5 more` + - `type: "response.reasoning_text.done"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The type of the event. Always `response.reasoning_text.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 + - `"response.reasoning_text.done"` - - `"eq"` + - `agent: optional object { agent_name }` - - `"ne"` + The agent that owns this multi-agent streaming event. - - `"gt"` + - `agent_name: string` - - `"gte"` + The canonical name of the agent that produced this item. - - `"lt"` + - `BetaResponseRefusalDeltaEvent object { content_index, delta, item_id, 4 more }` - - `"lte"` + Emitted when there is a partial refusal text. - - `"in"` + - `content_index: number` - - `"nin"` + The index of the content part that the refusal text is added to. - - `value: string or number or boolean or array of string or number` + - `delta: string` - The value to compare against the attribute key; supports string, number, or boolean types. + The refusal text that is added. - - `string` + - `item_id: string` - - `number` + The ID of the output item that the refusal text is added to. - - `boolean` + - `output_index: number` - - `array of string or number` + The index of the output item that the refusal text is added to. - - `string` + - `sequence_number: number` - - `number` + The sequence number of this event. - - `unknown` + - `type: "response.refusal.delta"` - - `type: "and" or "or"` + The type of the event. Always `response.refusal.delta`. - Type of operation: `and` or `or`. + - `"response.refusal.delta"` - - `"and"` + - `agent: optional object { agent_name }` - - `"or"` + The agent that owns this multi-agent streaming event. - - `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 }` + - `BetaResponseRefusalDoneEvent object { content_index, item_id, output_index, 4 more }` - Ranking options for search. + Emitted when refusal text is finalized. - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `content_index: number` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + The index of the content part that the refusal text is finalized. - - `embedding_weight: number` + - `item_id: string` - The weight of the embedding in the reciprocal ranking fusion. + The ID of the output item that the refusal text is finalized. - - `text_weight: number` + - `output_index: number` - The weight of the text in the reciprocal ranking fusion. + The index of the output item that the refusal text is finalized. - - `ranker: optional "auto" or "default-2024-11-15"` + - `refusal: string` - The ranker to use for the file search. + The refusal text that is finalized. - - `"auto"` + - `sequence_number: number` - - `"default-2024-11-15"` + The sequence number of this event. - - `score_threshold: optional number` + - `type: "response.refusal.done"` - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + The type of the event. Always `response.refusal.done`. - - `Computer object { type }` + - `"response.refusal.done"` - 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 }` - - `type: "computer"` + The agent that owns this multi-agent streaming event. - The type of the computer tool. Always `computer`. + - `agent_name: string` - - `"computer"` + The canonical name of the agent that produced this item. - - `ComputerUsePreview object { display_height, display_width, environment, type }` + - `BetaResponseTextDeltaEvent object { content_index, delta, item_id, 5 more }` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + Emitted when there is an additional text delta. - - `display_height: number` + - `content_index: number` - The height of the computer display. + The index of the content part that the text delta was added to. - - `display_width: number` + - `delta: string` - The width of the computer display. + The text delta that was added. - - `environment: "windows" or "mac" or "linux" or 2 more` + - `item_id: string` - The type of computer environment to control. + The ID of the output item that the text delta was added to. - - `"windows"` + - `logprobs: array of object { token, logprob, top_logprobs }` - - `"mac"` + The log probabilities of the tokens in the delta. - - `"linux"` + - `token: string` - - `"ubuntu"` + A possible text token. - - `"browser"` + - `logprob: number` - - `type: "computer_use_preview"` + The log probability of this token. - The type of the computer use tool. Always `computer_use_preview`. + - `top_logprobs: optional array of object { token, logprob }` - - `"computer_use_preview"` + The log probabilities of up to 20 of the most likely tokens. - - `WebSearch object { type, filters, search_context_size, user_location }` + - `token: optional string` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + A possible text token. - - `type: "web_search" or "web_search_2025_08_26"` + - `logprob: optional number` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + The log probability of this token. - - `"web_search"` + - `output_index: number` - - `"web_search_2025_08_26"` + The index of the output item that the text delta was added to. - - `filters: optional object { allowed_domains }` + - `sequence_number: number` - Filters for the search. + The sequence number for this event. - - `allowed_domains: optional array of string` + - `type: "response.output_text.delta"` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + The type of the event. Always `response.output_text.delta`. - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `"response.output_text.delta"` - - `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 owns this multi-agent streaming event. - - `"low"` + - `agent_name: string` - - `"medium"` + The canonical name of the agent that produced this item. - - `"high"` + - `BetaResponseTextDoneEvent object { content_index, item_id, logprobs, 5 more }` - - `user_location: optional object { city, country, region, 2 more }` + Emitted when text content is finalized. - The approximate location of the user. + - `content_index: number` - - `city: optional string` + The index of the content part that the text content is finalized. - Free text input for the city of the user, e.g. `San Francisco`. + - `item_id: string` - - `country: optional string` + The ID of the output item that the text content is finalized. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `logprobs: array of object { token, logprob, top_logprobs }` - - `region: optional string` + The log probabilities of the tokens in the delta. - Free text input for the region of the user, e.g. `California`. + - `token: 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: number` - - `type: optional "approximate"` + The log probability of this token. - The type of location approximation. Always `approximate`. + - `top_logprobs: optional array of object { token, logprob }` - - `"approximate"` + The log probabilities of up to 20 of the most likely tokens. - - `Mcp object { server_label, type, allowed_callers, 9 more }` + - `token: optional string` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + A possible text token. - - `server_label: string` + - `logprob: optional number` - A label for this MCP server, used to identify it in tool calls. + The log probability of this token. - - `type: "mcp"` + - `output_index: number` - The type of the MCP tool. Always `mcp`. + The index of the output item that the text content is finalized. - - `"mcp"` + - `sequence_number: number` - - `allowed_callers: optional array of "direct" or "programmatic"` + The sequence number for this event. - The tool invocation context(s). + - `text: string` - - `"direct"` + The text content that is finalized. - - `"programmatic"` + - `type: "response.output_text.done"` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + The type of the event. Always `response.output_text.done`. - List of allowed tool names or a filter object. + - `"response.output_text.done"` - - `McpAllowedTools = array of string` + - `agent: optional object { agent_name }` - A string array of allowed tool names + The agent that owns this multi-agent streaming event. - - `McpToolFilter 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` + - `BetaResponseWebSearchCallCompletedEvent object { item_id, output_index, sequence_number, 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. + Emitted when a web search call is completed. - - `tool_names: optional array of string` + - `item_id: string` - List of allowed tool names. + Unique ID for the output item associated with the web search call. - - `authorization: optional string` + - `output_index: 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. + The index of the output item that the web search call is associated with. - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + - `sequence_number: 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + The sequence number of the web search call being processed. - Currently supported `connector_id` values are: + - `type: "response.web_search_call.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` + The type of the event. Always `response.web_search_call.completed`. - - `"connector_dropbox"` + - `"response.web_search_call.completed"` - - `"connector_gmail"` + - `agent: optional object { agent_name }` - - `"connector_googlecalendar"` + The agent that owns this multi-agent streaming event. - - `"connector_googledrive"` + - `agent_name: string` - - `"connector_microsoftteams"` + The canonical name of the agent that produced this item. - - `"connector_outlookcalendar"` + - `BetaResponseWebSearchCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` - - `"connector_outlookemail"` + Emitted when a web search call is initiated. - - `"connector_sharepoint"` + - `item_id: string` - - `defer_loading: optional boolean` + Unique ID for the output item associated with the web search call. - Whether this MCP tool is deferred and discovered via tool search. + - `output_index: number` - - `headers: optional map[string]` + The index of the output item that the web search call is associated with. - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `sequence_number: number` - - `require_approval: optional object { always, never } or "always" or "never"` + The sequence number of the web search call being processed. - Specify which of the MCP server's tools require approval. + - `type: "response.web_search_call.in_progress"` - - `McpToolApprovalFilter object { always, never }` + The type of the event. Always `response.web_search_call.in_progress`. - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `"response.web_search_call.in_progress"` - - `always: optional object { read_only, tool_names }` + - `agent: optional object { agent_name }` - A filter object to specify which tools are allowed. + The agent that owns this multi-agent streaming event. - - `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` + - `BetaResponseWebSearchCallSearchingEvent object { item_id, output_index, sequence_number, 2 more }` - List of allowed tool names. + Emitted when a web search call is executing. - - `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.searching"` - 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.searching`. - - `"always"` + - `"response.web_search_call.searching"` - - `"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. + - `BetaResponseImageGenCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` - - `tunnel_id: optional string` + Emitted when an image generation tool call has completed and the final image is available. - 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. + - `item_id: string` - - `CodeInterpreter object { container, type, allowed_callers }` + The unique identifier of the image generation item being processed. - A tool that runs Python code to help generate a response to a prompt. + - `output_index: number` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + The index of the output item in the response's output array. - 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. + - `sequence_number: number` - - `string` + The sequence number of this event. - The container ID. + - `type: "response.image_generation_call.completed"` - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + The type of the event. Always 'response.image_generation_call.completed'. - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `"response.image_generation_call.completed"` - - `type: "auto"` + - `agent: optional object { agent_name }` - Always `auto`. + The agent that owns this multi-agent streaming event. - - `"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. + - `BetaResponseImageGenCallGeneratingEvent object { item_id, output_index, sequence_number, 2 more }` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + Emitted when an image generation tool call is actively generating an image (intermediate state). - The memory limit for the code interpreter container. + - `item_id: string` - - `"1g"` + The unique identifier of the image generation item being processed. - - `"4g"` + - `output_index: number` - - `"16g"` + The index of the output item in the response's output array. - - `"64g"` + - `sequence_number: number` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + The sequence number of the image generation item being processed. - Network access policy for the container. + - `type: "response.image_generation_call.generating"` - - `BetaContainerNetworkPolicyDisabled object { type }` + The type of the event. Always 'response.image_generation_call.generating'. - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `"response.image_generation_call.generating"` - - `type: "code_interpreter"` + - `agent: optional object { agent_name }` - The type of the code interpreter tool. Always `code_interpreter`. + The agent that owns this multi-agent streaming event. - - `"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). + - `BetaResponseImageGenCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` - - `"direct"` + Emitted when an image generation tool call is in progress. - - `"programmatic"` + - `item_id: string` - - `ProgrammaticToolCalling object { type }` + The unique identifier of the image generation item being processed. - - `type: "programmatic_tool_calling"` + - `output_index: number` - The type of the tool. Always `programmatic_tool_calling`. + The index of the output item in the response's output array. - - `"programmatic_tool_calling"` + - `sequence_number: number` - - `ImageGeneration object { type, action, background, 9 more }` + The sequence number of the image generation item being processed. - A tool that generates images using the GPT image models. + - `type: "response.image_generation_call.in_progress"` - - `type: "image_generation"` + The type of the event. Always 'response.image_generation_call.in_progress'. - The type of the image generation tool. Always `image_generation`. + - `"response.image_generation_call.in_progress"` - - `"image_generation"` + - `agent: optional object { agent_name }` - - `action: optional "generate" or "edit" or "auto"` + The agent that owns this multi-agent streaming event. - 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"` + - `BetaResponseImageGenCallPartialImageEvent object { item_id, output_index, partial_image_b64, 4 more }` - - `"auto"` + Emitted when a partial image is available during image generation streaming. - - `background: optional "transparent" or "opaque" or "auto"` + - `item_id: string` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + The unique identifier of the image generation item being processed. - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + - `output_index: number` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + The index of the output item in the response's output array. - - `"transparent"` + - `partial_image_b64: string` - - `"opaque"` + Base64-encoded partial image data, suitable for rendering as an image. - - `"auto"` + - `partial_image_index: number` - - `input_fidelity: optional "high" or "low"` + 0-based index for the partial image (backend is 1-based, but this is 0-based for the user). - 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`. + - `sequence_number: number` - - `"high"` + The sequence number of the image generation item being processed. - - `"low"` + - `type: "response.image_generation_call.partial_image"` - - `input_image_mask: optional object { file_id, image_url }` + The type of the event. Always 'response.image_generation_call.partial_image'. - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `"response.image_generation_call.partial_image"` - - `file_id: optional string` + - `agent: optional object { agent_name }` - File ID for the mask image. + The agent that owns this multi-agent streaming event. - - `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-2" or 3 more` + - `BetaResponseMcpCallArgumentsDeltaEvent object { delta, item_id, output_index, 3 more }` - The image generation model to use. Default: `gpt-image-1`. + Emitted when there is a delta (partial update) to the arguments of an MCP tool call. - - `string` + - `delta: string` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + A JSON string containing the partial update to the arguments for the MCP tool call. - The image generation model to use. Default: `gpt-image-1`. + - `item_id: string` - - `"gpt-image-1"` + The unique identifier of the MCP tool call item being processed. - - `"gpt-image-1-mini"` + - `output_index: number` - - `"gpt-image-2"` + The index of the output item in the response's output array. - - `"gpt-image-2-2026-04-21"` + - `sequence_number: number` - - `"gpt-image-1.5"` + The sequence number of this event. - - `"chatgpt-image-latest"` + - `type: "response.mcp_call_arguments.delta"` - - `moderation: optional "auto" or "low"` + The type of the event. Always 'response.mcp_call_arguments.delta'. - Moderation level for the generated image. Default: `auto`. + - `"response.mcp_call_arguments.delta"` - - `"auto"` + - `agent: optional object { agent_name }` - - `"low"` + The agent that owns this multi-agent streaming event. - - `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"` + - `BetaResponseMcpCallArgumentsDoneEvent object { arguments, item_id, output_index, 3 more }` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + Emitted when the arguments for an MCP tool call are finalized. - - `"png"` + - `arguments: string` - - `"webp"` + A JSON string containing the finalized arguments for the MCP tool call. - - `"jpeg"` + - `item_id: string` - - `partial_images: optional number` + The unique identifier of the MCP tool call item being processed. - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `output_index: number` - - `quality: optional "low" or "medium" or "high" or "auto"` + The index of the output item in the response's output array. - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `sequence_number: number` - - `"low"` + The sequence number of this event. - - `"medium"` + - `type: "response.mcp_call_arguments.done"` - - `"high"` + The type of the event. Always 'response.mcp_call_arguments.done'. - - `"auto"` + - `"response.mcp_call_arguments.done"` - - `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 owns this multi-agent streaming event. - - `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`. + - `BetaResponseMcpCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` - - `"1024x1024"` + Emitted when an MCP tool call has completed successfully. - - `"1024x1536"` + - `item_id: string` - - `"1536x1024"` + The ID of the MCP tool call item that completed. - - `"auto"` + - `output_index: number` - - `LocalShell object { type }` + The index of the output item that completed. - 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.completed"` - - `"local_shell"` + The type of the event. Always 'response.mcp_call.completed'. - - `Shell object { type, allowed_callers, environment }` + - `"response.mcp_call.completed"` - 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"` + - `BetaResponseMcpCallFailedEvent object { item_id, output_index, sequence_number, 2 more }` - The tool invocation context(s). + Emitted when an MCP tool call has failed. - - `"direct"` + - `item_id: string` - - `"programmatic"` + The ID of the MCP tool call item that failed. - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + - `output_index: number` - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + The index of the output item that failed. - - `BetaLocalEnvironment object { type, skills }` + - `sequence_number: number` - - `BetaContainerReference object { container_id, type }` + The sequence number of this event. - - `Custom object { name, type, allowed_callers, 3 more }` + - `type: "response.mcp_call.failed"` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The type of the event. Always 'response.mcp_call.failed'. - - `name: string` + - `"response.mcp_call.failed"` - The name of the custom tool, used to identify it in tool calls. + - `agent: optional object { agent_name }` - - `type: "custom"` + The agent that owns this multi-agent streaming event. - 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"` + - `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. - - `defer_loading: optional boolean` + - `output_index: number` - Whether this tool should be deferred and discovered via tool search. + The index of the output item in the response's output array. - - `description: optional string` + - `sequence_number: number` - Optional description of the custom tool, used to provide more context. + The sequence number of this event. - - `format: optional object { type } or object { definition, syntax, type }` + - `type: "response.mcp_call.in_progress"` - The input format for the custom tool. Default is unconstrained text. + The type of the event. Always 'response.mcp_call.in_progress'. - - `Text object { type }` + - `"response.mcp_call.in_progress"` - Unconstrained free-form text. + - `agent: optional object { agent_name }` - - `type: "text"` + The agent that owns this multi-agent streaming event. - Unconstrained text format. Always `text`. + - `agent_name: string` - - `"text"` + The canonical name of the agent that produced this item. - - `Grammar object { definition, syntax, type }` + - `BetaResponseMcpListToolsCompletedEvent object { item_id, output_index, sequence_number, 2 more }` - A grammar defined by the user. + Emitted when the list of available MCP tools has been successfully retrieved. - - `definition: string` + - `item_id: string` - The grammar definition. + The ID of the MCP tool call item that produced this output. - - `syntax: "lark" or "regex"` + - `output_index: number` - The syntax of the grammar definition. One of `lark` or `regex`. + The index of the output item that was processed. - - `"lark"` + - `sequence_number: number` - - `"regex"` + The sequence number of this event. - - `type: "grammar"` + - `type: "response.mcp_list_tools.completed"` - Grammar format. Always `grammar`. + The type of the event. Always 'response.mcp_list_tools.completed'. - - `"grammar"` + - `"response.mcp_list_tools.completed"` - - `Namespace object { description, name, tools, type }` + - `agent: optional object { agent_name }` - Groups function/custom tools under a shared namespace. + The agent that owns this multi-agent streaming event. - - `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` + - `BetaResponseMcpListToolsFailedEvent object { item_id, output_index, sequence_number, 2 more }` - The namespace name used in tool calls (for example, `crm`). + Emitted when the attempt to list available MCP tools has failed. - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + - `item_id: string` - The function/custom tools available inside this namespace. + The ID of the MCP tool call item that failed. - - `Function object { name, type, allowed_callers, 5 more }` + - `output_index: number` - - `name: string` + The index of the output item that failed. - - `type: "function"` + - `sequence_number: number` - - `"function"` + The sequence number of this event. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `type: "response.mcp_list_tools.failed"` - The tool invocation context(s). + The type of the event. Always 'response.mcp_list_tools.failed'. - - `"direct"` + - `"response.mcp_list_tools.failed"` - - `"programmatic"` + - `agent: optional object { agent_name }` - - `defer_loading: optional boolean` + The agent that owns this multi-agent streaming event. - Whether this function should be deferred and discovered via tool search. + - `agent_name: string` - - `description: optional string` + The canonical name of the agent that produced this item. - - `output_schema: optional map[unknown]` + - `BetaResponseMcpListToolsInProgressEvent object { item_id, output_index, sequence_number, 2 more }` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + Emitted when the system is in the process of retrieving the list of available MCP tools. - - `parameters: optional unknown` + - `item_id: string` - - `strict: optional boolean` + The ID of the MCP tool call item that is being processed. - 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. + - `output_index: number` - - `Custom object { name, type, allowed_callers, 3 more }` + The index of the output item that is being processed. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `sequence_number: number` - - `name: string` + The sequence number of this event. - The name of the custom tool, used to identify it in tool calls. + - `type: "response.mcp_list_tools.in_progress"` - - `type: "custom"` + The type of the event. Always 'response.mcp_list_tools.in_progress'. - The type of the custom tool. Always `custom`. + - `"response.mcp_list_tools.in_progress"` - - `"custom"` + - `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"` + - `BetaResponseOutputTextAnnotationAddedEvent object { annotation, annotation_index, content_index, 5 more }` - - `defer_loading: optional boolean` + Emitted when an annotation is added to output text content. - Whether this tool should be deferred and discovered via tool search. + - `annotation: unknown` - - `description: optional string` + The annotation object being added. (See annotation schema for details.) - Optional description of the custom tool, used to provide more context. + - `annotation_index: number` - - `format: optional object { type } or object { definition, syntax, type }` + The index of the annotation within the content part. - The input format for the custom tool. Default is unconstrained text. + - `content_index: number` - - `Text object { type }` + The index of the content part within the output item. - Unconstrained free-form text. + - `item_id: string` - - `type: "text"` + The unique identifier of the item to which the annotation is being added. - Unconstrained text format. Always `text`. + - `output_index: number` - - `"text"` + The index of the output item in the response's output array. - - `Grammar object { definition, syntax, type }` + - `sequence_number: number` - A grammar defined by the user. + The sequence number of this event. - - `definition: string` + - `type: "response.output_text.annotation.added"` - The grammar definition. + The type of the event. Always 'response.output_text.annotation.added'. - - `syntax: "lark" or "regex"` + - `"response.output_text.annotation.added"` - The syntax of the grammar definition. One of `lark` or `regex`. + - `agent: optional object { agent_name }` - - `"lark"` + The agent that owns this multi-agent streaming event. - - `"regex"` + - `agent_name: string` - - `type: "grammar"` + The canonical name of the agent that produced this item. - Grammar format. Always `grammar`. + - `BetaResponseQueuedEvent object { response, sequence_number, type, agent }` - - `"grammar"` + Emitted when a response is queued and waiting to be processed. - - `type: "namespace"` + - `response: BetaResponse` - The type of the tool. Always `namespace`. + The full response object that is queued. - - `"namespace"` + - `sequence_number: number` - - `ToolSearch object { type, description, execution, parameters }` + The sequence number for this event. - Hosted or BYOT tool search configuration for deferred tools. + - `type: "response.queued"` - - `type: "tool_search"` + The type of the event. Always 'response.queued'. - The type of the tool. Always `tool_search`. + - `"response.queued"` - - `"tool_search"` + - `agent: optional object { agent_name }` - - `description: optional string` + The agent that owns this multi-agent streaming event. - 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. + - `BetaResponseCustomToolCallInputDeltaEvent object { delta, item_id, output_index, 3 more }` - - `"server"` + Event representing a delta (partial update) to the input of a custom tool call. - - `"client"` + - `delta: string` - - `parameters: optional unknown` + The incremental input data (delta) for the custom tool call. - Parameter schema for a client-executed tool search tool. + - `item_id: string` - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + Unique identifier for the API item associated with this 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). + - `output_index: number` - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + The index of the output this delta applies 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 of this event. - - `"web_search_preview_2025_03_11"` + - `type: "response.custom_tool_call_input.delta"` - - `search_content_types: optional array of "text" or "image"` + The event type identifier. - - `"text"` + - `"response.custom_tool_call_input.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"` + - `BetaResponseCustomToolCallInputDoneEvent object { input, item_id, output_index, 3 more }` - - `"high"` + Event indicating that input for a custom tool call is complete. - - `user_location: optional object { type, city, country, 2 more }` + - `input: string` - The user's location. + The complete input data for the custom tool call. - - `type: "approximate"` + - `item_id: string` - The type of location approximation. Always `approximate`. + Unique identifier for the API item associated with this event. - - `"approximate"` + - `output_index: number` - - `city: optional string` + The index of the output this event applies to. - Free text input for the city of the user, e.g. `San Francisco`. + - `sequence_number: number` - - `country: optional string` + The sequence number of this event. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `type: "response.custom_tool_call_input.done"` - - `region: optional string` + The event type identifier. - Free text input for the region of the user, e.g. `California`. + - `"response.custom_tool_call_input.done"` - - `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 owns this multi-agent streaming event. - - `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"` + - `BetaResponseInjectCreatedEvent object { response_id, sequence_number, type, stream_id }` - The type of the tool. Always `apply_patch`. + Emitted when all injected input items were validated and committed to the + active response. - - `"apply_patch"` + - `response_id: string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The ID of the response that accepted the input. - The tool invocation context(s). + - `sequence_number: number` - - `"direct"` + The sequence number for this event. - - `"programmatic"` + - `type: "response.inject.created"` - - `top_logprobs: optional number` + The event discriminator. Always `response.inject.created`. - 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. + - `"response.inject.created"` - - `top_p: optional number` + - `stream_id: 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 multiplexed WebSocket stream that emitted the event. This field is + present only when WebSocket multiplexing is enabled separately. - We generally recommend altering this or `temperature` but not both. + - `BetaResponseInjectFailedEvent object { error, input, response_id, 3 more }` - - `truncation: optional "auto" or "disabled"` + 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 truncation strategy to use for the model response. + - `error: object { code, message }` - - `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. + Information about why the input was not committed. - - `"auto"` + - `code: "response_already_completed" or "response_not_found"` - - `"disabled"` + A machine-readable error code. - - `user: optional string` + - `"response_already_completed"` - 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](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `"response_not_found"` - - `ResponseInject object { input, response_id, type }` + - `message: string` - 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. + A human-readable description of the error. - `input: array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` - Input items to inject into the active response. + The raw input items that were not committed. - `BetaEasyInputMessage object { content, role, phase, type }` @@ -195629,7 +194749,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `FileSearchCall object { id, queries, status, 3 more }` The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + [file search guide](/docs/guides/tools-file-search) for more information. - `id: string` @@ -195705,7 +194825,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + [computer use guide](/docs/guides/tools-computer-use) for more information. - `id: string` @@ -195824,7 +194944,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `WebSearchCall object { id, action, status, 2 more }` The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + [web search guide](/docs/guides/tools-web-search) for more information. - `id: string` @@ -195928,7 +195048,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `FunctionCall object { arguments, call_id, name, 6 more }` A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + [function calling guide](/docs/guides/function-calling) for more information. - `arguments: string` @@ -196003,7 +195123,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The unique ID of the function tool call generated by the model. - - `output: string or BetaResponseFunctionCallOutputItemList` + - `output: string or array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` Text, image, or file output of the function tool call. @@ -196011,10 +195131,22 @@ curl -X POST https://api.openai.com/v1/responses/compact \ A JSON string of the output of the function tool call. - - `BetaResponseFunctionCallOutputItemList = array of BetaResponseFunctionCallOutputItem` + - `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 }` + + A file input to the model. + - `type: "function_call_output"` The type of the function tool call output. Always `function_call_output`. @@ -196085,7 +195217,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + An image input to the model. Learn about [image inputs](/docs/guides/vision) - `EncryptedContent object { encrypted_content, type }` @@ -196610,7 +195742,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-web-search). + [web search tool](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -196670,7 +195802,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -196722,7 +195854,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -196914,19 +196046,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `background: optional "transparent" or "opaque" or "auto"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. - - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. - - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - `"transparent"` @@ -196955,13 +196076,13 @@ curl -X POST https://api.openai.com/v1/responses/compact \ Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `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-2" or 3 more` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` The image generation model to use. Default: `gpt-image-1`. @@ -196969,14 +196090,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"gpt-image-1-mini"` - - `"gpt-image-2"` - - - `"gpt-image-2-2026-04-21"` - - `"gpt-image-1.5"` - - `"chatgpt-image-latest"` - - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -197073,7 +196188,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -197187,7 +196302,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -197668,7 +196783,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-web-search). + [web search tool](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -197728,7 +196843,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -197780,7 +196895,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -197972,19 +197087,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `background: optional "transparent" or "opaque" or "auto"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. - - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. - - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - `"transparent"` @@ -198013,13 +197117,13 @@ curl -X POST https://api.openai.com/v1/responses/compact \ Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `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-2" or 3 more` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` The image generation model to use. Default: `gpt-image-1`. @@ -198027,14 +197131,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"gpt-image-1-mini"` - - `"gpt-image-2"` - - - `"gpt-image-2-2026-04-21"` - - `"gpt-image-1.5"` - - `"chatgpt-image-latest"` - - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -198131,7 +197229,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -198245,7 +197343,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -198436,7 +197534,7 @@ curl -X POST https://api.openai.com/v1/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](https://platform.openai.com/docs/guides/conversation-state). + [managing context](/docs/guides/conversation-state). - `id: string` @@ -198502,7 +197600,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `Compaction object { encrypted_content, type, id, agent }` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). - `encrypted_content: string` @@ -198791,371 +197889,1330 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `Direct object { type }` - - `type: "direct"` + - `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. + + - `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` + + 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 }` + + - `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. + + - `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. + + - `"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"` + +### Beta Tool Choice Apply Patch + +- `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"` + +### Beta Tool Choice Custom + +- `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"` + +### Beta Tool Choice Function + +- `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"` + +### Beta Tool Choice Mcp + +- `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. + +### Beta Tool Choice Options + +- `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"` + +### Beta Tool Choice Shell + +- `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"` + +### Beta Tool Choice Types + +- `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"` + +# Input Items + +## List input items + +**get** `/responses/{response_id}/input_items?beta=true` + +Returns a list of input items for a given response. + +### Path Parameters + +- `response_id: string` + +### Query Parameters + +- `after: optional string` + + An item ID to list items after, used in pagination. + +- `include: optional array of BetaResponseIncludable` + + Additional fields to include in the response. See the `include` + parameter for Response creation above for more information. + + - `"file_search_call.results"` + + - `"web_search_call.results"` + + - `"web_search_call.action.sources"` + + - `"message.input_image.image_url"` + + - `"computer_call_output.output.image_url"` + + - `"code_interpreter_call.outputs"` + + - `"reasoning.encrypted_content"` - The caller type. Always `direct`. + - `"message.output_text.logprobs"` - - `"direct"` +- `limit: optional number` - - `Program object { caller_id, type }` + A limit on the number of objects to be returned. Limit can range between + 1 and 100, and the default is 20. - - `caller_id: string` +- `order: optional "asc" or "desc"` - The call ID of the program item that produced this tool call. + The order to return the input items in. Default is `desc`. - - `type: "program"` + - `asc`: Return the input items in ascending order. + - `desc`: Return the input items in descending order. - The caller type. Always `program`. + - `"asc"` - - `"program"` + - `"desc"` - - `environment: optional BetaLocalEnvironment or BetaContainerReference` +### Header Parameters - The environment to execute the shell commands in. +- `"openai-beta": optional array of "responses_multi_agent=v1"` - - `BetaLocalEnvironment object { type, skills }` + - `"responses_multi_agent=v1"` - - `BetaContainerReference object { container_id, type }` +### Returns - - `status: optional "in_progress" or "completed" or "incomplete"` +- `BetaResponseItemList object { data, first_id, has_more, 2 more }` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + A list of Response items. - - `"in_progress"` + - `data: array of BetaResponseInputMessageItem or BetaResponseOutputMessage or object { id, queries, status, 3 more } or 29 more` - - `"completed"` + A list of items used to generate this response. - - `"incomplete"` + - `BetaResponseInputMessageItem object { id, content, role, 3 more }` - - `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 message input. - - `call_id: string` + - `content: BetaResponseInputMessageContentList` - The unique ID of the shell tool call generated by the model. + A list of one or many input items to the model, containing different content + types. - - `output: array of BetaResponseFunctionShellCallOutputContent` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - Captured chunks of stdout and stderr output, along with their associated outcomes. + A text input to the model. - - `outcome: object { type } or object { exit_code, type }` + - `text: string` - The exit or timeout outcome associated with this shell call. + The text input to the model. - - `stderr: string` + - `type: "input_text"` - Captured stderr output for the shell call. + The type of the input item. Always `input_text`. - - `stdout: string` + - `"input_text"` - Captured stdout output for the shell call. + - `prompt_cache_breakpoint: optional object { mode }` - - `type: "shell_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 item. Always `shell_call_output`. + - `mode: "explicit"` - - `"shell_call_output"` + The breakpoint mode. Always `explicit`. - - `id: optional string` + - `"explicit"` - The unique ID of the shell tool call output. Populated when this item is returned via API. + - `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 produced this item. + - `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"` - - `caller: optional object { type } or object { caller_id, type }` + - `"high"` - The execution context that produced this tool call. + - `"auto"` - - `Direct object { type }` + - `"original"` - - `type: "direct"` + - `type: "input_image"` - The caller type. Always `direct`. + The type of the input item. Always `input_image`. - - `"direct"` + - `"input_image"` - - `Program object { caller_id, type }` + - `file_id: optional string` - - `caller_id: string` + The ID of the file to be sent to the model. - The call ID of the program item that produced this tool call. + - `image_url: optional string` - - `type: "program"` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - The caller type. Always `program`. + - `prompt_cache_breakpoint: optional object { mode }` - - `"program"` + Marks the exact end of a reusable 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"` - The maximum number of UTF-8 characters captured for this shell call's combined output. + The breakpoint mode. Always `explicit`. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"explicit"` - The status of the shell call output. + - `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`. - - `ApplyPatchCall object { call_id, operation, status, 4 more }` + - `"input_file"` - A tool call representing a request to create, delete, or update files using diff patches. + - `detail: optional "auto" or "low" or "high"` - - `call_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 unique ID of the apply patch tool call generated by the model. + - `"auto"` - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + - `"low"` - The specific create, delete, or update instruction for the apply_patch tool call. + - `"high"` - - `CreateFile object { diff, path, type }` + - `file_data: optional string` - Instruction for creating a new file via the apply_patch tool. + The content of the file to be sent to the model. - - `diff: string` + - `file_id: optional string` - Unified diff content to apply when creating the file. + The ID of the file to be sent to the model. - - `path: string` + - `file_url: optional string` - Path of the file to create relative to the workspace root. + The URL of the file to be sent to the model. - - `type: "create_file"` + - `filename: optional string` - The operation type. Always `create_file`. + The name of the file to be sent to the model. - - `"create_file"` + - `prompt_cache_breakpoint: optional object { mode }` - - `DeleteFile object { 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 for deleting an existing file via the apply_patch tool. + - `mode: "explicit"` - - `path: string` + The breakpoint mode. Always `explicit`. - Path of the file to delete relative to the workspace root. + - `"explicit"` - - `type: "delete_file"` + - `role: "user" or "system" or "developer"` - The operation type. Always `delete_file`. + The role of the message input. One of `user`, `system`, or `developer`. - - `"delete_file"` + - `"user"` - - `UpdateFile object { diff, path, type }` + - `"system"` - Instruction for updating an existing file via the apply_patch tool. + - `"developer"` - - `diff: string` + - `type: "message"` - Unified diff content to apply to the existing file. + The type of the message input. Always set to `message`. - - `path: string` + - `"message"` - Path of the file to update relative to the workspace root. + - `agent: optional object { agent_name }` - - `type: "update_file"` + The agent that produced this item. - The operation type. Always `update_file`. + - `agent_name: string` - - `"update_file"` + The canonical name of the agent that produced this item. - - `status: "in_progress" or "completed"` + - `status: optional "in_progress" or "completed" or "incomplete"` - The status of the apply patch tool call. One of `in_progress` or `completed`. + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `"in_progress"` - `"completed"` - - `type: "apply_patch_call"` + - `"incomplete"` - The type of the item. Always `apply_patch_call`. + - `BetaResponseOutputMessage object { id, content, role, 4 more }` - - `"apply_patch_call"` + An output message from the model. - - `id: optional string` + - `id: string` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + The unique ID of the output message. - - `agent: optional object { agent_name }` + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - The agent that produced this item. + The content of the output message. - - `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. - - `caller: optional object { type } or object { caller_id, type }` + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` - The execution context that produced this tool call. + The annotations of the text output. - - `Direct object { type }` + - `FileCitation object { file_id, filename, index, type }` - - `type: "direct"` + A citation to a file. - The caller type. Always `direct`. + - `file_id: string` - - `"direct"` + The ID of the file. - - `Program object { caller_id, type }` + - `filename: string` - - `caller_id: string` + The filename of the file cited. - The call ID of the program item that produced this tool call. + - `index: number` - - `type: "program"` + The index of the file in the list of files. - The caller type. Always `program`. + - `type: "file_citation"` - - `"program"` + The type of the file citation. Always `file_citation`. - - `ApplyPatchCallOutput object { call_id, status, type, 4 more }` + - `"file_citation"` - The streamed output emitted by an apply patch tool call. + - `URLCitation object { end_index, start_index, title, 2 more }` - - `call_id: string` + A citation for a web resource used to generate a model response. - The unique ID of the apply patch tool call generated by the model. + - `end_index: number` - - `status: "completed" or "failed"` + The index of the last character of the URL citation in the message. - The status of the apply patch tool call output. One of `completed` or `failed`. + - `start_index: number` - - `"completed"` + The index of the first character of the URL citation in the message. - - `"failed"` + - `title: string` - - `type: "apply_patch_call_output"` + The title of the web resource. - The type of the item. Always `apply_patch_call_output`. + - `type: "url_citation"` - - `"apply_patch_call_output"` + The type of the URL citation. Always `url_citation`. - - `id: optional string` + - `"url_citation"` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `url: string` - - `agent: optional object { agent_name }` + The URL of the web resource. - The agent that produced this item. + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - - `agent_name: string` + A citation for a container file used to generate a model response. - The canonical name of the agent that produced this item. + - `container_id: string` - - `caller: optional object { type } or object { caller_id, type }` + The ID of the container file. - The execution context that produced this tool call. + - `end_index: number` - - `Direct object { type }` + The index of the last character of the container file citation in the message. - - `type: "direct"` + - `file_id: string` - The caller type. Always `direct`. + The ID of the file. - - `"direct"` + - `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"` - The caller type. Always `program`. + The type of the container file citation. Always `container_file_citation`. - - `"program"` + - `"container_file_citation"` - - `output: optional string` + - `FilePath object { file_id, index, type }` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + A path to a file. - - `McpListTools object { id, server_label, tools, 3 more }` + - `file_id: string` - A list of tools available on an MCP server. + The ID of the file. - - `id: string` + - `index: number` - The unique ID of the list. + The index of the file in the list of files. - - `server_label: string` + - `type: "file_path"` - The label of the MCP server. + The type of the file path. Always `file_path`. - - `tools: array of object { input_schema, name, annotations, description }` + - `"file_path"` - The tools available on the server. + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - - `input_schema: unknown` + - `token: string` - The JSON schema describing the tool's input. + - `bytes: array of number` - - `name: string` + - `logprob: number` - The name of the tool. + - `top_logprobs: array of object { token, bytes, logprob }` - - `annotations: optional unknown` + - `token: string` - Additional annotations about the tool. + - `bytes: array of number` - - `description: optional string` + - `logprob: number` - The description of the tool. + - `text: string` - - `type: "mcp_list_tools"` + The text output from the model. - The type of the item. Always `mcp_list_tools`. + - `type: "output_text"` - - `"mcp_list_tools"` + The type of the output text. Always `output_text`. - - `agent: optional object { agent_name }` + - `"output_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. + - `refusal: string` - - `error: optional string` + The refusal explanation from the model. - Error message if the server could not list tools. + - `type: "refusal"` - - `McpApprovalRequest object { id, arguments, name, 3 more }` + The type of the refusal. Always `refusal`. - A request for human approval of a tool invocation. + - `"refusal"` - - `id: string` + - `role: "assistant"` - The unique ID of the approval request. + The role of the output message. Always `assistant`. - - `arguments: string` + - `"assistant"` - A JSON string of arguments for the tool. + - `status: "in_progress" or "completed" or "incomplete"` - - `name: string` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - The name of the tool to run. + - `"in_progress"` - - `server_label: string` + - `"completed"` - The label of the MCP server making the request. + - `"incomplete"` - - `type: "mcp_approval_request"` + - `type: "message"` - The type of the item. Always `mcp_approval_request`. + The type of the output message. Always `message`. - - `"mcp_approval_request"` + - `"message"` - `agent: optional object { agent_name }` @@ -199165,27 +199222,49 @@ 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 }` + - `phase: optional "commentary" or "final_answer"` - A response to an MCP approval request. + 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. - - `approval_request_id: string` + - `"commentary"` - The ID of the approval request being answered. + - `"final_answer"` - - `approve: boolean` + - `FileSearchCall object { id, queries, status, 3 more }` - Whether the request was approved. + The results of a file search tool call. See the + [file search guide](/docs/guides/tools-file-search) for more information. - - `type: "mcp_approval_response"` + - `id: string` - The type of the item. Always `mcp_approval_response`. + The unique ID of the file search tool call. - - `"mcp_approval_response"` + - `queries: array of string` - - `id: optional string` + The queries used to search for files. - The unique ID of the approval response + - `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 }` @@ -199195,60 +199274,73 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `reason: optional string` + - `results: optional array of object { attributes, file_id, filename, 2 more }` - Optional reason for the decision. + The results of the file search tool call. - - `McpCall object { id, arguments, name, 7 more }` + - `attributes: optional map[string or number or boolean]` - An invocation of a tool on an MCP server. + 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: string` + - `string` - The unique ID of the tool call. + - `number` - - `arguments: string` + - `boolean` - A JSON string of the arguments passed to the tool. + - `file_id: optional string` - - `name: string` + The unique ID of the file. - The name of the tool that was run. + - `filename: optional string` - - `server_label: string` + The name of the file. - The label of the MCP server running the tool. + - `score: optional number` - - `type: "mcp_call"` + The relevance score of the file - a value between 0 and 1. - The type of the item. Always `mcp_call`. + - `text: optional string` - - `"mcp_call"` + The text that was retrieved from the file. - - `agent: optional object { agent_name }` + - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` - The agent that produced this item. + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - - `agent_name: string` + - `id: string` - The canonical name of the agent that produced this item. + The unique ID of the computer call. - - `approval_request_id: optional string` + - `call_id: string` - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + An identifier used when responding to the tool call with output. - - `error: optional string` + - `pending_safety_checks: array of object { id, code, message }` - The error from the tool call, if any. + The pending safety checks for the computer call. - - `output: optional string` + - `id: string` - The output from the tool call. + The ID of the pending safety check. - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `code: optional string` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + 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"` @@ -199256,242 +199348,247 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"incomplete"` - - `"calling"` + - `type: "computer_call"` - - `"failed"` + The type of the computer call. Always `computer_call`. - - `CustomToolCallOutput object { call_id, output, type, 3 more }` + - `"computer_call"` - The output of a custom tool call from your code, being sent back to the model. + - `action: optional BetaComputerAction` - - `call_id: string` + A click action. - The call ID, used to map this custom tool call output to a custom tool call. + - `Click object { button, type, x, 2 more }` - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + A click action. - The output from the custom tool 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 custom tool call. + - `"left"` - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `"right"` - Text, image, or file output of the custom tool 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](https://platform.openai.com/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` - - `type: "custom_tool_call_output"` + The x-coordinate where the click occurred. - The type of the custom tool call output. Always `custom_tool_call_output`. + - `y: number` - - `"custom_tool_call_output"` + The y-coordinate where the click occurred. - - `id: optional string` + - `keys: optional array of string` - The unique ID of the custom tool call output in the OpenAI platform. + The keys being held while clicking. - - `agent: optional object { agent_name }` + - `DoubleClick object { keys, type, x, y }` - The agent that produced this item. + A double click action. - - `agent_name: string` + - `keys: array of string` - The canonical name of the agent that produced this item. + The keys being held while double-clicking. - - `caller: optional object { type } or object { caller_id, type }` + - `type: "double_click"` - The execution context that produced this tool call. + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `Direct object { type }` + - `"double_click"` - - `type: "direct"` + - `x: number` - The caller type. Always `direct`. + The x-coordinate where the double click occurred. - - `"direct"` + - `y: number` - - `Program object { caller_id, type }` + The y-coordinate where the double click occurred. - - `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"` + - `path: array of object { x, y }` - The caller type. Always `program`. + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `"program"` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `CustomToolCall object { call_id, input, name, 5 more }` + - `x: number` - A call to a custom tool created by the model. + The x-coordinate. - - `call_id: string` + - `y: number` - An identifier used to map this custom tool call to a tool call output. + The y-coordinate. - - `input: string` + - `type: "drag"` - The input for the custom tool call generated by the model. + Specifies the event type. For a drag action, this property is always set to `drag`. - - `name: string` + - `"drag"` - The name of the custom tool being called. + - `keys: optional array of string` - - `type: "custom_tool_call"` + The keys being held while dragging the mouse. - The type of the custom tool call. Always `custom_tool_call`. + - `Keypress object { keys, type }` - - `"custom_tool_call"` + A collection of keypresses the model would like to perform. - - `id: optional string` + - `keys: array of string` - The unique ID of the custom tool call in the OpenAI platform. + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `agent: optional object { agent_name }` + - `type: "keypress"` - The agent that produced this item. + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `agent_name: string` + - `"keypress"` - The canonical name of the agent that produced this item. + - `Move object { type, x, y, keys }` - - `caller: optional object { type } or object { caller_id, type }` + A mouse move action. - The execution context that produced this tool call. + - `type: "move"` - - `Direct object { type }` + Specifies the event type. For a move action, this property is always set to `move`. - - `type: "direct"` + - `"move"` - - `"direct"` + - `x: number` - - `Program object { caller_id, type }` + The x-coordinate to move to. - - `caller_id: string` + - `y: number` - The call ID of the program item that produced this tool call. + The y-coordinate to move to. - - `type: "program"` + - `keys: optional array of string` - - `"program"` + The keys being held while moving the mouse. - - `namespace: optional string` + - `Screenshot object { type }` - The namespace of the custom tool being called. + A screenshot action. - - `CompactionTrigger object { type, agent }` + - `type: "screenshot"` - Compacts the current context. Must be the final input item. + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `type: "compaction_trigger"` + - `"screenshot"` - The type of the item. Always `compaction_trigger`. + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - - `"compaction_trigger"` + A scroll action. - - `agent: optional object { agent_name }` + - `scroll_x: number` - The agent that produced this item. + The horizontal scroll distance. - - `agent_name: string` + - `scroll_y: number` - The canonical name of the agent that produced this item. + The vertical scroll distance. - - `ItemReference object { id, agent, type }` + - `type: "scroll"` - An internal identifier for an item to reference. + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `id: string` + - `"scroll"` - The ID of the item to reference. + - `x: number` - - `agent: optional object { agent_name }` + The x-coordinate where the scroll occurred. - The agent that produced this item. + - `y: number` - - `agent_name: string` + The y-coordinate where the scroll occurred. - The canonical name of the agent that produced this item. + - `keys: optional array of string` - - `type: optional "item_reference"` + The keys being held while scrolling. - The type of item to reference. Always `item_reference`. + - `Type object { text, type }` - - `"item_reference"` + An action to type in text. - - `Program object { id, call_id, code, 3 more }` + - `text: string` - - `id: string` + The text to type. - The unique ID of this program item. + - `type: "type"` - - `call_id: string` + Specifies the event type. For a type action, this property is always set to `type`. - The stable call ID of the program item. + - `"type"` - - `code: string` + - `Wait object { type }` - The JavaScript source executed by programmatic tool calling. + A wait action. - - `fingerprint: string` + - `type: "wait"` - Opaque program replay fingerprint that must be round-tripped. + Specifies the event type. For a wait action, this property is always set to `wait`. - - `type: "program"` + - `"wait"` - The item type. Always `program`. + - `actions: optional BetaComputerActionList` - - `"program"` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `agent: optional object { agent_name }` + - `Click object { button, type, x, 2 more }` - The agent that produced this item. + A click action. - - `agent_name: string` + - `DoubleClick object { keys, type, x, y }` - The canonical name of the agent that produced this item. + A double click action. - - `ProgramOutput object { id, call_id, result, 3 more }` + - `Drag object { path, type, keys }` - - `id: string` + A drag action. - The unique ID of this program output item. + - `Keypress object { keys, type }` - - `call_id: string` + A collection of keypresses the model would like to perform. - The call ID of the program item. + - `Move object { type, x, y, keys }` - - `result: string` + A mouse move action. - The result produced by the program item. + - `Screenshot object { type }` - - `status: "completed" or "incomplete"` + A screenshot action. - The terminal status of the program output. + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - - `"completed"` + A scroll action. - - `"incomplete"` + - `Type object { text, type }` - - `type: "program_output"` + An action to type in text. - The item type. Always `program_output`. + - `Wait object { type }` - - `"program_output"` + A wait action. - `agent: optional object { agent_name }` @@ -199501,425 +199598,421 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `response_id: string` + - `ComputerCallOutput object { id, call_id, output, 5 more }` - The ID of the active response that should receive the input. + - `id: string` - - `type: "response.inject"` + The unique ID of the computer call tool output. - The event discriminator. Always `response.inject`. + - `call_id: string` - - `"response.inject"` + The ID of the computer tool call that produced the output. -### Beta Responses Server Event + - `output: BetaResponseComputerToolCallOutputScreenshot` -- `BetaResponsesServerEvent = BetaResponseAudioDeltaEvent or BetaResponseAudioDoneEvent or BetaResponseAudioTranscriptDeltaEvent or 52 more` + A computer screenshot image used with the computer use tool. - Server events emitted by the Responses WebSocket server. + - `type: "computer_screenshot"` - - `BetaResponseAudioDeltaEvent object { delta, sequence_number, type, agent }` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - Emitted when there is a partial audio response. + - `"computer_screenshot"` - - `delta: string` + - `file_id: optional string` - A chunk of Base64 encoded response audio bytes. + The identifier of an uploaded file that contains the screenshot. - - `sequence_number: number` + - `image_url: optional string` - A sequence number for this chunk of the stream response. + The URL of the screenshot image. - - `type: "response.audio.delta"` + - `status: "completed" or "incomplete" or "failed" or "in_progress"` - The type of the event. Always `response.audio.delta`. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `"response.audio.delta"` + - `"completed"` - - `agent: optional object { agent_name }` + - `"incomplete"` - The agent that owns this multi-agent streaming event. + - `"failed"` - - `agent_name: string` + - `"in_progress"` - The canonical name of the agent that produced this item. + - `type: "computer_call_output"` - - `BetaResponseAudioDoneEvent object { sequence_number, type, agent }` + The type of the computer tool call output. Always `computer_call_output`. - Emitted when the audio response is complete. + - `"computer_call_output"` - - `sequence_number: number` + - `acknowledged_safety_checks: optional array of object { id, code, message }` - The sequence number of the delta. + The safety checks reported by the API that have been acknowledged by the + developer. - - `type: "response.audio.done"` + - `id: string` - The type of the event. Always `response.audio.done`. + The ID of the pending safety check. - - `"response.audio.done"` + - `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 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. - - `BetaResponseAudioTranscriptDeltaEvent object { delta, sequence_number, type, agent }` + - `created_by: optional string` - Emitted when there is a partial transcript of audio. + The identifier of the actor that created the item. - - `delta: string` + - `WebSearchCall object { id, action, status, 2 more }` - The partial transcript of the audio response. + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. - - `sequence_number: number` + - `id: string` - The sequence number of this event. + The unique ID of the web search tool call. - - `type: "response.audio.transcript.delta"` + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - The type of the event. Always `response.audio.transcript.delta`. + 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). - - `"response.audio.transcript.delta"` + - `Search object { type, queries, query, sources }` - - `agent: optional object { agent_name }` + Action type "search" - Performs a web search query. - The agent that owns this multi-agent streaming event. + - `type: "search"` - - `agent_name: string` + The action type. - The canonical name of the agent that produced this item. + - `"search"` - - `BetaResponseAudioTranscriptDoneEvent object { sequence_number, type, agent }` + - `queries: optional array of string` - Emitted when the full audio transcript is completed. + The search queries. - - `sequence_number: number` + - `query: optional string` - The sequence number of this event. + The search query. - - `type: "response.audio.transcript.done"` + - `sources: optional array of object { type, url }` - The type of the event. Always `response.audio.transcript.done`. + The sources used in the search. - - `"response.audio.transcript.done"` + - `type: "url"` - - `agent: optional object { agent_name }` + The type of source. Always `url`. - The agent that owns this multi-agent streaming event. + - `"url"` - - `agent_name: string` + - `url: string` - The canonical name of the agent that produced this item. + The URL of the source. - - `BetaResponseCodeInterpreterCallCodeDeltaEvent object { delta, item_id, output_index, 3 more }` + - `OpenPage object { type, url }` - Emitted when a partial code snippet is streamed by the code interpreter. + Action type "open_page" - Opens a specific URL from search results. - - `delta: string` + - `type: "open_page"` - The partial code snippet being streamed by the code interpreter. + The action type. - - `item_id: string` + - `"open_page"` - The unique identifier of the code interpreter tool call item. + - `url: optional string` - - `output_index: number` + The URL opened by the model. - The index of the output item in the response for which the code is being streamed. + - `FindInPage object { pattern, type, url }` - - `sequence_number: number` + Action type "find_in_page": Searches for a pattern within a loaded page. - The sequence number of this event, used to order streaming events. + - `pattern: string` - - `type: "response.code_interpreter_call_code.delta"` + The pattern or text to search for within the page. - The type of the event. Always `response.code_interpreter_call_code.delta`. + - `type: "find_in_page"` - - `"response.code_interpreter_call_code.delta"` + The action type. - - `agent: optional object { agent_name }` + - `"find_in_page"` - The agent that owns this multi-agent streaming event. + - `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"` - - `BetaResponseCodeInterpreterCallCodeDoneEvent object { code, item_id, output_index, 3 more }` + The status of the web search tool call. - Emitted when the code snippet is finalized by the code interpreter. + - `"in_progress"` - - `code: string` + - `"searching"` - The final code snippet output by the code interpreter. + - `"completed"` - - `item_id: string` + - `"failed"` - The unique identifier of the code interpreter tool call item. + - `type: "web_search_call"` - - `output_index: number` + The type of the web search tool call. Always `web_search_call`. - The index of the output item in the response for which the code is finalized. + - `"web_search_call"` - - `sequence_number: number` + - `agent: optional object { agent_name }` - The sequence number of this event, used to order streaming events. + The agent that produced this item. - - `type: "response.code_interpreter_call_code.done"` + - `agent_name: string` - The type of the event. Always `response.code_interpreter_call_code.done`. + The canonical name of the agent that produced this item. - - `"response.code_interpreter_call_code.done"` + - `FunctionCall object { id, arguments, call_id, 7 more }` - - `agent: optional object { agent_name }` + - `id: string` - The agent that owns this multi-agent streaming event. + The unique ID of the function tool call. - - `agent_name: string` + - `arguments: string` - The canonical name of the agent that produced this item. + A JSON string of the arguments to pass to the function. - - `BetaResponseCodeInterpreterCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` + - `call_id: string` - Emitted when the code interpreter call is completed. + The unique ID of the function tool call generated by the model. - - `item_id: string` + - `name: string` - The unique identifier of the code interpreter tool call item. + The name of the function to run. - - `output_index: number` + - `status: "in_progress" or "completed" or "incomplete"` - The index of the output item in the response for which the code interpreter call is completed. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `sequence_number: number` + - `"in_progress"` - The sequence number of this event, used to order streaming events. + - `"completed"` - - `type: "response.code_interpreter_call.completed"` + - `"incomplete"` - The type of the event. Always `response.code_interpreter_call.completed`. + - `type: "function_call"` - - `"response.code_interpreter_call.completed"` + The type of the function tool call. Always `function_call`. + + - `"function_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. - - `BetaResponseCodeInterpreterCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` - - Emitted when a code interpreter call is in progress. - - - `item_id: string` - - The unique identifier of the code interpreter tool call item. - - - `output_index: number` + - `caller: optional object { type } or object { caller_id, type }` - The index of the output item in the response for which the code interpreter call is in progress. + The execution context that produced this tool call. - - `sequence_number: number` + - `Direct object { type }` - The sequence number of this event, used to order streaming events. + - `type: "direct"` - - `type: "response.code_interpreter_call.in_progress"` + - `"direct"` - The type of the event. Always `response.code_interpreter_call.in_progress`. + - `Program object { caller_id, type }` - - `"response.code_interpreter_call.in_progress"` + - `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` + - `"program"` - The canonical name of the agent that produced this item. + - `created_by: optional string` - - `BetaResponseCodeInterpreterCallInterpretingEvent object { item_id, output_index, sequence_number, 2 more }` + The identifier of the actor that created the item. - Emitted when the code interpreter is actively interpreting the code snippet. + - `namespace: optional string` - - `item_id: string` + The namespace of the function to run. - The unique identifier of the code interpreter tool call item. + - `FunctionCallOutput object { id, call_id, output, 5 more }` - - `output_index: number` + - `id: string` - The index of the output item in the response for which the code interpreter is interpreting code. + The unique ID of the function call tool output. - - `sequence_number: number` + - `call_id: string` - The sequence number of this event, used to order streaming events. + The unique ID of the function tool call generated by the model. - - `type: "response.code_interpreter_call.interpreting"` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - The type of the event. Always `response.code_interpreter_call.interpreting`. + The output from the function call generated by your code. + Can be a string or an list of output content. - - `"response.code_interpreter_call.interpreting"` + - `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 }` - - `BetaResponseCompletedEvent object { response, sequence_number, type, agent }` + A text input to the model. - Emitted when the model response is complete. + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `response: BetaResponse` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - Properties of the completed response. + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `id: string` + A file input to the model. - Unique identifier for this Response. + - `status: "in_progress" or "completed" or "incomplete"` - - `created_at: number` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Unix timestamp (in seconds) of when this Response was created. + - `"in_progress"` - - `error: BetaResponseError` + - `"completed"` - An error object returned when the model fails to generate a Response. + - `"incomplete"` - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 16 more` + - `type: "function_call_output"` - The error code for the response. + The type of the function tool call output. Always `function_call_output`. - - `"server_error"` + - `"function_call_output"` - - `"rate_limit_exceeded"` + - `agent: optional object { agent_name }` - - `"invalid_prompt"` + The agent that produced this item. - - `"bio_policy"` + - `agent_name: string` - - `"vector_store_timeout"` + The canonical name of the agent that produced this item. - - `"invalid_image"` + - `caller: optional object { type } or object { caller_id, type }` - - `"invalid_image_format"` + The execution context that produced this tool call. - - `"invalid_base64_image"` + - `Direct object { type }` - - `"invalid_image_url"` + - `type: "direct"` - - `"image_too_large"` + The caller type. Always `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"` + The caller type. Always `program`. - - `"empty_image_file"` + - `"program"` - - `"failed_to_download_image"` + - `created_by: optional string` - - `"image_file_not_found"` + The identifier of the actor that created the item. - - `message: string` + - `AgentMessage object { id, author, content, 3 more }` - A human-readable description of the error. + - `id: string` - - `incomplete_details: object { reason }` + The unique ID of the agent message. - Details about why the response is incomplete. + - `author: string` - - `reason: optional "max_output_tokens" or "content_filter"` + The sending agent identity. - The reason why the response is incomplete. + - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` - - `"max_output_tokens"` + Encrypted content sent between agents. - - `"content_filter"` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `instructions: string or array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + A text input to the model. - A system (or developer) message inserted into the model's context. + - `BetaResponseOutputText object { annotations, logprobs, text, 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. + A text output from the model. - - `string` + - `Text object { text, type }` - A text input to the model, equivalent to a text input with the - `developer` role. + A text content. - - `InputItemList = array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + - `text: string` - A list of one or many input items to the model, containing - different content types. + - `type: "text"` - - `BetaEasyInputMessage object { content, role, phase, type }` + - `"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. + - `SummaryText object { text, type }` - - `content: string or BetaResponseInputMessageContentList` + A summary text from the model. - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + - `text: string` - - `TextInput = string` + A summary of the reasoning output from the model so far. - A text input to the model. + - `type: "summary_text"` - - `BetaResponseInputMessageContentList = array of BetaResponseInputContent` + The type of the object. Always `summary_text`. - A list of one or many input items to the model, containing different content - types. + - `"summary_text"` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `ReasoningText object { text, type }` - A text input to the model. + Reasoning text from the model. - `text: string` - The text input to the model. - - - `type: "input_text"` + The reasoning text from the model. - The type of the input item. Always `input_text`. + - `type: "reasoning_text"` - - `"input_text"` + The type of the reasoning text. Always `reasoning_text`. - - `prompt_cache_breakpoint: optional object { mode }` + - `"reasoning_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. + - `BetaResponseOutputRefusal object { refusal, type }` - - `mode: "explicit"` + A refusal from 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). - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + A screenshot of a computer. - `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`. + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - `"low"` @@ -199929,19 +200022,19 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"original"` - - `type: "input_image"` + - `file_id: string` - The type of the input item. Always `input_image`. + The identifier of an uploaded file that contains the screenshot. - - `"input_image"` + - `image_url: string` - - `file_id: optional string` + The URL of the screenshot image. - The ID of the file to be sent to the model. + - `type: "computer_screenshot"` - - `image_url: optional string` + Specifies the event type. For a computer screenshot, this property is always set to `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. + - `"computer_screenshot"` - `prompt_cache_breakpoint: optional object { mode }` @@ -199957,97 +200050,73 @@ curl -X POST https://api.openai.com/v1/responses/compact \ 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. + - `EncryptedContent object { encrypted_content, type }` - - `file_id: optional string` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - The ID of the file to be sent to the model. + - `encrypted_content: string` - - `file_url: optional string` + Opaque encrypted content. - The URL of the file to be sent to the model. + - `type: "encrypted_content"` - - `filename: optional string` + The type of the input item. Always `encrypted_content`. - The name of the file to be sent to the model. + - `"encrypted_content"` - - `prompt_cache_breakpoint: optional object { mode }` + - `recipient: 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 destination agent identity. - - `mode: "explicit"` + - `type: "agent_message"` - The breakpoint mode. Always `explicit`. + The type of the item. Always `agent_message`. - - `"explicit"` + - `"agent_message"` - - `role: "user" or "assistant" or "system" or "developer"` + - `agent: optional object { agent_name }` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + The agent that produced this item. - - `"user"` + - `agent_name: string` - - `"assistant"` + The canonical name of the agent that produced this item. - - `"system"` + - `MultiAgentCall object { id, action, arguments, 3 more }` - - `"developer"` + - `id: string` - - `phase: optional "commentary" or "final_answer"` + The unique ID of the multi-agent call 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. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `"commentary"` + The multi-agent action to execute. - - `"final_answer"` + - `"spawn_agent"` - - `type: optional "message"` + - `"interrupt_agent"` - The type of the message input. Always `message`. + - `"list_agents"` - - `"message"` + - `"send_message"` - - `Message object { content, role, agent, 2 more }` + - `"followup_task"` - 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. + - `"wait_agent"` - - `content: BetaResponseInputMessageContentList` + - `arguments: string` - A list of one or many input items to the model, containing different content - types. + The JSON string of arguments generated for the action. - - `role: "user" or "system" or "developer"` + - `call_id: string` - The role of the message input. One of `user`, `system`, or `developer`. + The unique ID linking this call to its output. - - `"user"` + - `type: "multi_agent_call"` - - `"system"` + The type of the multi-agent call. Always `multi_agent_call`. - - `"developer"` + - `"multi_agent_call"` - `agent: optional object { agent_name }` @@ -200057,1258 +200126,1290 @@ 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. + - `MultiAgentCallOutput object { id, action, call_id, 3 more }` - - `"in_progress"` + - `id: string` - - `"completed"` + The unique ID of the multi-agent call output item. - - `"incomplete"` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `type: optional "message"` + The multi-agent action that produced this result. - The type of the message input. Always set to `message`. + - `"spawn_agent"` - - `"message"` + - `"interrupt_agent"` - - `BetaResponseOutputMessage object { id, content, role, 4 more }` + - `"list_agents"` - An output message from the model. + - `"send_message"` - - `id: string` + - `"followup_task"` - The unique ID of the output message. + - `"wait_agent"` - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + - `call_id: string` - The content of the output message. + The unique ID of the multi-agent call. - - `BetaResponseOutputText object { annotations, text, type, logprobs }` + - `output: array of BetaResponseOutputText` - A text output from the model. + 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. - - `FileCitation object { file_id, filename, index, type }` + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - A citation to a file. + - `text: string` - - `file_id: string` + The text output from the model. - The ID of the file. + - `type: "output_text"` - - `filename: string` + The type of the output text. Always `output_text`. - The filename of the file cited. + - `type: "multi_agent_call_output"` - - `index: number` + The type of the multi-agent result. Always `multi_agent_call_output`. - The index of the file in the list of files. + - `"multi_agent_call_output"` - - `type: "file_citation"` + - `agent: optional object { agent_name }` - The type of the file citation. 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. - A citation for a web resource used to generate a model response. + - `ToolSearchCall object { id, arguments, call_id, 5 more }` - - `end_index: number` + - `id: string` - The index of the last character of the URL citation in the message. + The unique ID of the tool search call item. - - `start_index: number` + - `arguments: unknown` - The index of the first character of the URL citation in the message. + Arguments used for the tool search call. - - `title: string` + - `call_id: string` - The title of the web resource. + The unique ID of the tool search call generated by the model. - - `type: "url_citation"` + - `execution: "server" or "client"` - The type of the URL citation. Always `url_citation`. + Whether tool search was executed by the server or by the client. - - `"url_citation"` + - `"server"` - - `url: string` + - `"client"` - 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 tool search call item that was recorded. - 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: "tool_search_call"` - The index of the last character of the container file citation in the message. + The type of the item. Always `tool_search_call`. - - `file_id: string` + - `"tool_search_call"` - 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. + - `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`. + - `ToolSearchOutput object { id, call_id, execution, 5 more }` - - `"container_file_citation"` + - `id: string` - - `FilePath object { file_id, index, type }` + The unique ID of the tool search output item. - A path to a file. + - `call_id: string` - - `file_id: string` + The unique ID of the tool search call generated by the model. - The ID of the file. + - `execution: "server" or "client"` - - `index: number` + Whether tool search was executed by the server or by the client. - The index of the file in the list of files. + - `"server"` - - `type: "file_path"` + - `"client"` - The type of the file path. Always `file_path`. + - `status: "in_progress" or "completed" or "incomplete"` - - `"file_path"` + 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. - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + - `Function object { name, parameters, strict, 5 more }` - - `token: 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). - - `bytes: array of number` + - `name: string` - - `logprob: number` + The name of the function to call. - - `top_logprobs: array of object { token, bytes, logprob }` + - `parameters: map[unknown]` - - `token: string` + A JSON schema object describing the parameters of the function. - - `bytes: array of number` + - `strict: boolean` - - `logprob: number` + Whether strict parameter validation is enforced for this function tool. - - `BetaResponseOutputRefusal object { refusal, type }` + - `type: "function"` - A refusal from the model. + The type of the function tool. Always `function`. - - `refusal: string` + - `"function"` - The refusal explanation from the model. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `type: "refusal"` + The tool invocation context(s). - The type of the refusal. Always `refusal`. + - `"direct"` - - `"refusal"` + - `"programmatic"` - - `role: "assistant"` + - `defer_loading: optional boolean` - The role of the output message. Always `assistant`. + Whether this function is deferred and loaded via tool search. - - `"assistant"` + - `description: optional string` - - `status: "in_progress" or "completed" or "incomplete"` + A description of the function. Used by the model to determine whether or not to call the function. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `output_schema: optional map[unknown]` - - `"in_progress"` + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `"completed"` + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - - `"incomplete"` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `type: "message"` + - `type: "file_search"` - The type of the output message. Always `message`. + The type of the file search tool. Always `file_search`. - - `"message"` + - `"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. - - `phase: optional "commentary" or "final_answer"` + - `ComparisonFilter object { key, type, value }` - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `"commentary"` + - `key: string` - - `"final_answer"` + The key to compare against the value. - - `FileSearchCall object { id, queries, status, 3 more }` + - `type: "eq" or "ne" or "gt" or 5 more` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `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 ID of the file search tool call. + - `"eq"` - - `queries: array of string` + - `"ne"` - The queries used to search for files. + - `"gt"` - - `status: "in_progress" or "searching" or "completed" or 2 more` + - `"gte"` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `"lt"` - - `"in_progress"` + - `"lte"` - - `"searching"` + - `"in"` - - `"completed"` + - `"nin"` - - `"incomplete"` + - `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: "file_search_call"` + - `string` - The type of the file search tool call. Always `file_search_call`. + - `number` - - `"file_search_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 }` - - `results: optional array of object { attributes, file_id, filename, 2 more }` + Combine multiple filters using `and` or `or`. - The results of the file search tool call. + - `filters: array of object { key, type, value } or unknown` - - `attributes: optional map[string or number or boolean]` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - 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. + - `ComparisonFilter object { key, type, value }` - - `string` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `number` + - `key: string` - - `boolean` + The key to compare against the value. - - `file_id: optional string` + - `type: "eq" or "ne" or "gt" or 5 more` - The unique ID of the file. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `filename: 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 name of the file. + - `"eq"` - - `score: optional number` + - `"ne"` - The relevance score of the file - a value between 0 and 1. + - `"gt"` - - `text: optional string` + - `"gte"` - The text that was retrieved from the file. + - `"lt"` - - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` + - `"lte"` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + - `"in"` - - `id: string` + - `"nin"` - The unique ID of the computer 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. - An identifier used when responding to the tool call with output. + - `string` - - `pending_safety_checks: array of object { id, code, message }` + - `number` - The pending safety checks for the computer call. + - `boolean` - - `id: string` + - `array of string or number` - The ID of the pending safety check. + - `string` - - `code: optional string` + - `number` - The type of the pending safety check. + - `unknown` - - `message: optional string` + - `type: "and" or "or"` - Details about the pending safety check. + Type of operation: `and` or `or`. - - `status: "in_progress" or "completed" or "incomplete"` + - `"and"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"or"` - - `"in_progress"` + - `max_num_results: optional number` - - `"completed"` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `"incomplete"` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `type: "computer_call"` + Ranking options for search. - The type of the computer call. Always `computer_call`. + - `hybrid_search: optional object { embedding_weight, text_weight }` - - `"computer_call"` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `action: optional BetaComputerAction` + - `embedding_weight: number` - A click action. + The weight of the embedding in the reciprocal ranking fusion. - - `Click object { button, type, x, 2 more }` + - `text_weight: number` - A click action. + The weight of the text in the reciprocal ranking fusion. - - `button: "left" or "right" or "wheel" or 2 more` + - `ranker: optional "auto" or "default-2024-11-15"` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + The ranker to use for the file search. - - `"left"` + - `"auto"` - - `"right"` + - `"default-2024-11-15"` - - `"wheel"` + - `score_threshold: optional number` - - `"back"` + 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. - - `"forward"` + - `Computer object { type }` - - `type: "click"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - Specifies the event type. For a click action, this property is always `click`. + - `type: "computer"` - - `"click"` + The type of the computer tool. Always `computer`. - - `x: number` + - `"computer"` - The x-coordinate where the click occurred. + - `ComputerUsePreview object { display_height, display_width, environment, type }` - - `y: number` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The y-coordinate where the click occurred. + - `display_height: number` - - `keys: optional array of string` + The height of the computer display. - The keys being held while clicking. + - `display_width: number` - - `DoubleClick object { keys, type, x, y }` + The width of the computer display. - A double click action. + - `environment: "windows" or "mac" or "linux" or 2 more` - - `keys: array of string` + The type of computer environment to control. - The keys being held while double-clicking. + - `"windows"` - - `type: "double_click"` + - `"mac"` - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `"linux"` - - `"double_click"` + - `"ubuntu"` - - `x: number` + - `"browser"` - The x-coordinate where the double click occurred. + - `type: "computer_use_preview"` - - `y: number` + The type of the computer use tool. Always `computer_use_preview`. - The y-coordinate where the double click occurred. + - `"computer_use_preview"` - - `Drag object { path, type, keys }` + - `WebSearch object { type, filters, search_context_size, user_location }` - A drag action. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - - `path: array of object { x, y }` + - `type: "web_search" or "web_search_2025_08_26"` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `"web_search"` - - `x: number` + - `"web_search_2025_08_26"` - The x-coordinate. + - `filters: optional object { allowed_domains }` - - `y: number` + Filters for the search. - The y-coordinate. + - `allowed_domains: optional array of string` - - `type: "drag"` + 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 drag action, this property is always set to `drag`. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `"drag"` + - `search_context_size: optional "low" or "medium" or "high"` - - `keys: optional array of 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 keys being held while dragging the mouse. + - `"low"` - - `Keypress object { keys, type }` + - `"medium"` - A collection of keypresses the model would like to perform. + - `"high"` - - `keys: array of string` + - `user_location: optional object { city, country, region, 2 more }` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + The approximate location of the user. - - `type: "keypress"` + - `city: optional string` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + Free text input for the city of the user, e.g. `San Francisco`. - - `"keypress"` + - `country: optional string` - - `Move object { type, x, y, keys }` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - A mouse move action. + - `region: optional string` - - `type: "move"` + Free text input for the region of the user, e.g. `California`. - Specifies the event type. For a move action, this property is always set to `move`. + - `timezone: optional string` - - `"move"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `x: number` + - `type: optional "approximate"` - The x-coordinate to move to. + The type of location approximation. Always `approximate`. - - `y: number` + - `"approximate"` - The y-coordinate to move to. + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `keys: optional 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). - The keys being held while moving the mouse. + - `server_label: string` - - `Screenshot object { type }` + A label for this MCP server, used to identify it in tool calls. - A screenshot action. + - `type: "mcp"` - - `type: "screenshot"` + The type of the MCP tool. Always `mcp`. - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `"mcp"` - - `"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. + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `scroll_y: number` + List of allowed tool names or a filter object. - The vertical scroll distance. + - `McpAllowedTools = array of string` - - `type: "scroll"` + A string array of allowed tool names - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `McpToolFilter object { read_only, tool_names }` - - `"scroll"` + A filter object to specify which tools are allowed. - - `x: number` + - `read_only: optional boolean` - The x-coordinate where the scroll occurred. + 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. - - `y: number` + - `tool_names: optional array of string` - The y-coordinate where the scroll occurred. + List of allowed tool names. - - `keys: optional array of string` + - `authorization: optional string` - The keys being held while scrolling. + 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 object { text, type }` + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - An action to type in text. + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). - - `text: string` + Currently supported `connector_id` values are: - The text to 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` - - `type: "type"` + - `"connector_dropbox"` - Specifies the event type. For a type action, this property is always set to `type`. + - `"connector_gmail"` - - `"type"` + - `"connector_googlecalendar"` - - `Wait object { type }` + - `"connector_googledrive"` - A wait action. + - `"connector_microsoftteams"` - - `type: "wait"` + - `"connector_outlookcalendar"` - Specifies the event type. For a wait action, this property is always set to `wait`. + - `"connector_outlookemail"` - - `"wait"` + - `"connector_sharepoint"` - - `actions: optional BetaComputerActionList` + - `defer_loading: optional boolean` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + Whether this MCP tool is deferred and discovered via tool search. - - `Click object { button, type, x, 2 more }` + - `headers: optional map[string]` - A click action. + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `DoubleClick object { keys, type, x, y }` + - `require_approval: optional object { always, never } or "always" or "never"` - A double click action. + Specify which of the MCP server's tools require approval. - - `Drag object { path, type, keys }` + - `McpToolApprovalFilter object { always, never }` - A drag action. + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `Keypress object { keys, type }` + - `always: optional object { read_only, tool_names }` - A collection of keypresses the model would like to perform. + A filter object to specify which tools are allowed. - - `Move object { type, x, y, keys }` + - `read_only: optional boolean` - A mouse move action. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `Screenshot object { type }` + - `tool_names: optional array of string` - A screenshot action. + List of allowed tool names. - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `never: optional object { read_only, tool_names }` - A scroll action. + A filter object to specify which tools are allowed. - - `Type object { text, type }` + - `read_only: optional boolean` - An action to type in text. + 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. - - `Wait object { type }` + - `tool_names: optional array of string` - A wait action. + List of allowed tool names. - - `agent: optional object { agent_name }` + - `McpToolApprovalSetting = "always" or "never"` - 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. - - `agent_name: string` + - `"always"` - The canonical name of the agent that produced this item. + - `"never"` - - `ComputerCallOutput object { call_id, output, type, 4 more }` + - `server_description: optional string` - The output of a computer tool call. + Optional description of the MCP server, used to provide more context. - - `call_id: string` + - `server_url: optional string` - The ID of the computer tool call that produced the output. + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `tunnel_id: optional string` - A computer screenshot image used with the computer use tool. + 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: "computer_screenshot"` + - `CodeInterpreter object { container, type, allowed_callers }` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + A tool that runs Python code to help generate a response to a prompt. - - `"computer_screenshot"` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `file_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 identifier of an uploaded file that contains the screenshot. + - `string` - - `image_url: optional string` + The container ID. - The URL of the screenshot image. + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - - `type: "computer_call_output"` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - The type of the computer tool call output. Always `computer_call_output`. + - `type: "auto"` - - `"computer_call_output"` + Always `auto`. - - `id: optional string` + - `"auto"` - The ID of the computer tool call output. + - `file_ids: optional array of string` - - `acknowledged_safety_checks: optional array of object { id, code, message }` + An optional list of uploaded files to make available to your code. - The safety checks reported by the API that have been acknowledged by the developer. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `id: string` + The memory limit for the code interpreter container. - The ID of the pending safety check. + - `"1g"` - - `code: optional string` + - `"4g"` - The type of the pending safety check. + - `"16g"` - - `message: optional string` + - `"64g"` - Details about the pending safety check. + - `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` + - `type: "disabled"` - The canonical name of the agent that produced this item. + Disable outbound network access. Always `disabled`. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"disabled"` - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `"in_progress"` + - `allowed_domains: array of string` - - `"completed"` + A list of allowed domains when type is `allowlist`. - - `"incomplete"` + - `type: "allowlist"` - - `WebSearchCall object { id, action, status, 2 more }` + Allow outbound network access only to specified domains. Always `allowlist`. - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `"allowlist"` - - `id: string` + - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` - The unique ID of the web search tool call. + Optional domain-scoped secrets for allowlisted domains. - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + - `domain: 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). + The domain associated with the secret. - - `Search object { type, queries, query, sources }` + - `name: string` - Action type "search" - Performs a web search query. + The name of the secret to inject for the domain. - - `type: "search"` + - `value: string` - The action type. + The secret value to inject for the domain. - - `"search"` + - `type: "code_interpreter"` - - `queries: optional array of string` + The type of the code interpreter tool. Always `code_interpreter`. - The search queries. + - `"code_interpreter"` - - `query: optional string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The search query. + The tool invocation context(s). - - `sources: optional array of object { type, url }` + - `"direct"` - The sources used in the search. + - `"programmatic"` - - `type: "url"` + - `ProgrammaticToolCalling object { type }` - The type of source. Always `url`. + - `type: "programmatic_tool_calling"` - - `"url"` + The type of the tool. Always `programmatic_tool_calling`. - - `url: string` + - `"programmatic_tool_calling"` - The URL of the source. + - `ImageGeneration object { type, action, background, 9 more }` - - `OpenPage object { type, url }` + A tool that generates images using the GPT image models. - Action type "open_page" - Opens a specific URL from search results. + - `type: "image_generation"` - - `type: "open_page"` + The type of the image generation tool. Always `image_generation`. - The action type. + - `"image_generation"` - - `"open_page"` + - `action: optional "generate" or "edit" or "auto"` - - `url: optional string` + Whether to generate a new image or edit an existing image. Default: `auto`. - The URL opened by the model. + - `"generate"` - - `FindInPage object { pattern, type, url }` + - `"edit"` - Action type "find_in_page": Searches for a pattern within a loaded page. + - `"auto"` - - `pattern: string` + - `background: optional "transparent" or "opaque" or "auto"` - The pattern or text to search for within the page. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - - `type: "find_in_page"` + - `"transparent"` - The action type. + - `"opaque"` - - `"find_in_page"` + - `"auto"` - - `url: string` + - `input_fidelity: optional "high" or "low"` - The URL of the page searched for the pattern. + 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 "searching" or "completed" or "failed"` + - `"high"` - The status of the web search tool call. + - `"low"` - - `"in_progress"` + - `input_image_mask: optional object { file_id, image_url }` - - `"searching"` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `"completed"` + - `file_id: optional string` - - `"failed"` + File ID for the mask image. - - `type: "web_search_call"` + - `image_url: optional string` - The type of the web search tool call. Always `web_search_call`. + Base64-encoded mask image. - - `"web_search_call"` + - `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`. - - `FunctionCall object { arguments, call_id, name, 6 more }` + - `"gpt-image-1"` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `"gpt-image-1-mini"` - - `arguments: string` + - `"gpt-image-1.5"` - A JSON string of the arguments to pass to the function. + - `moderation: optional "auto" or "low"` - - `call_id: string` + Moderation level for the generated image. Default: `auto`. - The unique ID of the function tool call generated by the model. + - `"auto"` - - `name: string` + - `"low"` - The name of the function to run. + - `output_compression: optional number` - - `type: "function_call"` + 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"` - The type of the function tool call. Always `function_call`. + - `"jpeg"` - - `"function_call"` + - `partial_images: optional number` - - `id: optional string` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - The unique ID of the function tool 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"` - - `caller: optional object { type } or object { caller_id, type }` + - `"auto"` - The execution context that produced this tool call. + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `Direct object { type }` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `type: "direct"` + - `string` - - `"direct"` + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `Program object { caller_id, type }` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `caller_id: string` + - `"1024x1024"` - The call ID of the program item that produced this tool call. + - `"1024x1536"` - - `type: "program"` + - `"1536x1024"` - - `"program"` + - `"auto"` - - `namespace: optional string` + - `LocalShell object { type }` - The namespace of the function to run. + A tool that allows the model to execute shell commands in a local environment. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `type: "local_shell"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The type of the local shell tool. Always `local_shell`. - - `"in_progress"` + - `"local_shell"` - - `"completed"` + - `Shell object { type, allowed_callers, environment }` - - `"incomplete"` + A tool that allows the model to execute shell commands. - - `FunctionCallOutput object { call_id, output, type, 4 more }` + - `type: "shell"` - The output of a function tool call. + The type of the shell tool. Always `shell`. - - `call_id: string` + - `"shell"` - The unique ID of the function tool call generated by the model. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `output: string or BetaResponseFunctionCallOutputItemList` + The tool invocation context(s). - Text, image, or file output of the function tool call. + - `"direct"` - - `string` + - `"programmatic"` - A JSON string of the output of the function tool call. + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - `BetaResponseFunctionCallOutputItemList = array of BetaResponseFunctionCallOutputItem` + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - An array of content outputs (text, image, file) for the function tool call. + - `type: "container_auto"` - - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` + Automatically creates a container for this request - A text input to the model. + - `"container_auto"` - - `text: string` + - `file_ids: optional array of string` - The text input to the model. + An optional list of uploaded files to make available to your code. - - `type: "input_text"` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - The type of the input item. Always `input_text`. + The memory limit for the container. - - `"input_text"` + - `"1g"` - - `prompt_cache_breakpoint: optional object { mode }` + - `"4g"` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `"16g"` - - `mode: "explicit"` + - `"64g"` - The breakpoint mode. Always `explicit`. + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `"explicit"` + Network access policy for the container. - - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` + - `BetaContainerNetworkPolicyDisabled object { type }` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `type: "input_image"` + - `skills: optional array of BetaSkillReference or BetaInlineSkill` - The type of the input item. Always `input_image`. + An optional list of skills referenced by id or inline data. - - `"input_image"` + - `BetaSkillReference object { skill_id, type, version }` - - `detail: optional "low" or "high" or "auto" or "original"` + - `skill_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 ID of the referenced skill. - - `"low"` + - `type: "skill_reference"` - - `"high"` + References a skill created with the /v1/skills endpoint. - - `"auto"` + - `"skill_reference"` - - `"original"` + - `version: optional string` - - `file_id: optional string` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - The ID of the file to be sent to the model. + - `BetaInlineSkill object { description, name, source, type }` - - `image_url: optional string` + - `description: 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 description of the skill. - - `prompt_cache_breakpoint: optional object { mode }` + - `name: string` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The name of the skill. - - `mode: "explicit"` + - `source: BetaInlineSkillSource` - The breakpoint mode. Always `explicit`. + Inline skill payload - - `"explicit"` + - `data: string` - - `BetaResponseInputFileContent object { type, detail, file_data, 4 more }` + Base64-encoded skill zip bundle. - A file input to the model. + - `media_type: "application/zip"` - - `type: "input_file"` + The media type of the inline skill payload. Must be `application/zip`. - The type of the input item. Always `input_file`. + - `"application/zip"` - - `"input_file"` + - `type: "base64"` - - `detail: optional "auto" or "low" or "high"` + The type of the inline skill source. Must be `base64`. - 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`. + - `"base64"` - - `"auto"` + - `type: "inline"` - - `"low"` + Defines an inline skill for this request. - - `"high"` + - `"inline"` - - `file_data: optional string` + - `BetaLocalEnvironment object { type, skills }` - The base64-encoded data of the file to be sent to the model. + - `type: "local"` - - `file_id: optional string` + Use a local computer environment. - The ID of the file to be sent to the model. + - `"local"` - - `file_url: optional string` + - `skills: optional array of BetaLocalSkill` - The URL of the file to be sent to the model. + An optional list of skills. - - `filename: optional string` + - `description: string` - The name of the file to be sent to the model. + The description of the skill. - - `prompt_cache_breakpoint: optional object { mode }` + - `name: string` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The name of the skill. - - `mode: "explicit"` + - `path: string` - The breakpoint mode. Always `explicit`. + The path to the directory containing the skill. - - `"explicit"` + - `BetaContainerReference object { container_id, type }` - - `type: "function_call_output"` + - `container_id: string` - The type of the function tool call output. Always `function_call_output`. + The ID of the referenced container. - - `"function_call_output"` + - `type: "container_reference"` - - `id: optional string` + References a container created with the /v1/containers endpoint - The unique ID of the function tool call output. Populated when this item is returned via API. + - `"container_reference"` - - `agent: optional object { agent_name }` + - `Custom object { name, type, allowed_callers, 3 more }` - 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) - - `agent_name: string` + - `name: string` - The canonical name of the agent that produced this item. + The name of the custom tool, used to identify it in tool calls. - - `caller: optional object { type } or object { caller_id, type }` + - `type: "custom"` - The execution context that produced this tool call. + The type of the custom tool. Always `custom`. - - `Direct object { type }` + - `"custom"` - - `type: "direct"` + - `allowed_callers: optional array of "direct" or "programmatic"` - The caller type. Always `direct`. + The tool invocation context(s). - `"direct"` - - `Program object { caller_id, type }` + - `"programmatic"` - - `caller_id: string` + - `defer_loading: optional boolean` - The call ID of the program item that produced this tool call. + Whether this tool should be deferred and discovered via tool search. - - `type: "program"` + - `description: optional string` - 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](https://platform.openai.com/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 array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` + - `"grammar"` - Citations associated with the text content. + - `type: "namespace"` - - `array of 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"` - - `array of 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"` - - `array of 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 }` @@ -201318,33 +201419,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 }` @@ -201607,7 +201714,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-web-search). + [web search tool](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -201667,7 +201774,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -201719,7 +201826,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -201865,40 +201972,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`. @@ -201943,19 +202018,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `background: optional "transparent" or "opaque" or "auto"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. - - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. - - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - `"transparent"` @@ -201984,13 +202048,13 @@ curl -X POST https://api.openai.com/v1/responses/compact \ Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `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-2" or 3 more` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` The image generation model to use. Default: `gpt-image-1`. @@ -201998,14 +202062,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"gpt-image-1-mini"` - - `"gpt-image-2"` - - - `"gpt-image-2-2026-04-21"` - - `"gpt-image-1.5"` - - `"chatgpt-image-latest"` - - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -202096,131 +202154,127 @@ 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"` + - `BetaLocalEnvironment object { type, skills }` - - `file_ids: optional array of string` + - `BetaContainerReference object { container_id, type }` - An optional list of uploaded files to make available to your code. + - `Custom object { name, type, allowed_callers, 3 more }` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - The memory limit for the container. + - `name: string` - - `"1g"` + The name of the custom tool, used to identify it in tool calls. - - `"4g"` + - `type: "custom"` - - `"16g"` + The type of the custom tool. Always `custom`. - - `"64g"` + - `"custom"` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `allowed_callers: optional array of "direct" or "programmatic"` - Network access policy for the container. + The tool invocation context(s). - - `BetaContainerNetworkPolicyDisabled object { type }` + - `"direct"` - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `"programmatic"` - - `skills: optional array of BetaSkillReference or BetaInlineSkill` + - `defer_loading: optional boolean` - An optional list of skills referenced by id or inline data. + Whether this tool should be deferred and discovered via tool search. - - `BetaSkillReference object { skill_id, type, version }` + - `description: optional string` - - `skill_id: string` + Optional description of the custom tool, used to provide more context. - The ID of the referenced skill. + - `format: optional object { type } or object { definition, syntax, type }` - - `type: "skill_reference"` + The input format for the custom tool. Default is unconstrained text. - References a skill created with the /v1/skills endpoint. + - `Text object { type }` - - `"skill_reference"` + Unconstrained free-form text. - - `version: optional string` + - `type: "text"` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + Unconstrained text format. Always `text`. - - `BetaInlineSkill object { description, name, source, type }` + - `"text"` - - `description: string` + - `Grammar object { definition, syntax, type }` - The description of the skill. + A grammar defined by the user. - - `name: string` + - `definition: string` - The name of the skill. + The grammar definition. - - `source: BetaInlineSkillSource` + - `syntax: "lark" or "regex"` - Inline skill payload + The syntax of the grammar definition. One of `lark` or `regex`. - - `data: string` + - `"lark"` - Base64-encoded skill zip bundle. + - `"regex"` - - `media_type: "application/zip"` + - `type: "grammar"` - The media type of the inline skill payload. Must be `application/zip`. + Grammar format. Always `grammar`. - - `"application/zip"` + - `"grammar"` - - `type: "base64"` + - `Namespace object { description, name, tools, type }` - The type of the inline skill source. Must be `base64`. + Groups function/custom tools under a shared namespace. - - `"base64"` + - `description: string` - - `type: "inline"` + A description of the namespace shown to the model. - Defines an inline skill for this request. + - `name: string` - - `"inline"` + The namespace name used in tool calls (for example, `crm`). - - `BetaLocalEnvironment object { type, skills }` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - - `type: "local"` + The function/custom tools available inside this namespace. - Use a local computer environment. + - `Function object { name, type, allowed_callers, 5 more }` - - `"local"` + - `name: string` - - `skills: optional array of BetaLocalSkill` + - `type: "function"` - An optional list of skills. + - `"function"` - - `description: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The description of the skill. + The tool invocation context(s). - - `name: string` + - `"direct"` - The name of the skill. + - `"programmatic"` - - `path: string` + - `defer_loading: optional boolean` - The path to the directory containing the skill. + Whether this function should be deferred and discovered via tool search. - - `BetaContainerReference object { container_id, type }` + - `description: optional string` - - `container_id: string` + - `output_schema: optional map[unknown]` - The ID of the referenced container. + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `type: "container_reference"` + - `parameters: optional unknown` - References a container created with the /v1/containers endpoint + - `strict: optional boolean` - - `"container_reference"` + 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](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -202240,1335 +202294,1706 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"programmatic"` - - `defer_loading: optional boolean` + - `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. + + - `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 - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `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. + + - `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` - Whether this tool should be deferred and discovered via tool search. + The canonical name of the agent that produced this item. - - `description: optional string` + - `CodeInterpreterCall object { id, code, container_id, 4 more }` - Optional description of the custom tool, used to provide more context. + A tool call to run code. - - `format: optional object { type } or object { definition, syntax, type }` + - `id: string` - The input format for the custom tool. Default is unconstrained text. + The unique ID of the code interpreter tool call. - - `Text object { type }` + - `code: string` - Unconstrained free-form text. + The code to run, or null if not available. - - `type: "text"` + - `container_id: string` - Unconstrained text format. Always `text`. + The ID of the container used to run the code. - - `"text"` + - `outputs: array of object { logs, type } or object { type, url }` - - `Grammar object { definition, syntax, type }` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - A grammar defined by the user. + - `Logs object { logs, type }` - - `definition: string` + The logs output from the code interpreter. - The grammar definition. + - `logs: string` - - `syntax: "lark" or "regex"` + The logs output from the code interpreter. - The syntax of the grammar definition. One of `lark` or `regex`. + - `type: "logs"` - - `"lark"` + The type of the output. Always `logs`. - - `"regex"` + - `"logs"` - - `type: "grammar"` + - `Image object { type, url }` - Grammar format. Always `grammar`. + The image output from the code interpreter. - - `"grammar"` + - `type: "image"` - - `Namespace object { description, name, tools, type }` + The type of the output. Always `image`. - Groups function/custom tools under a shared namespace. + - `"image"` - - `description: string` + - `url: string` - A description of the namespace shown to the model. + The URL of the image output from the code interpreter. - - `name: string` + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - The namespace name used in tool calls (for example, `crm`). + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + - `"in_progress"` - The function/custom tools available inside this namespace. + - `"completed"` - - `Function object { name, type, allowed_callers, 5 more }` + - `"incomplete"` - - `name: string` + - `"interpreting"` - - `type: "function"` + - `"failed"` - - `"function"` + - `type: "code_interpreter_call"` - - `allowed_callers: optional array of "direct" or "programmatic"` + The type of the code interpreter tool call. Always `code_interpreter_call`. - The tool invocation context(s). + - `"code_interpreter_call"` - - `"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` + - `LocalShellCall object { id, action, call_id, 3 more }` - - `output_schema: optional map[unknown]` + A tool call to run a command on the local shell. - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `id: string` - - `parameters: optional unknown` + The unique ID of the local shell call. - - `strict: optional boolean` + - `action: object { command, env, type, 3 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. + Execute a shell command on the server. - - `Custom object { name, type, allowed_callers, 3 more }` + - `command: array of string` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The command to run. - - `name: string` + - `env: map[string]` - The name of the custom tool, used to identify it in tool calls. + Environment variables to set for the command. - - `type: "custom"` + - `type: "exec"` - The type of the custom tool. Always `custom`. + The type of the local shell action. Always `exec`. - - `"custom"` + - `"exec"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `timeout_ms: optional number` - The tool invocation context(s). + Optional timeout in milliseconds for the command. - - `"direct"` + - `user: optional string` - - `"programmatic"` + Optional user to run the command as. - - `defer_loading: optional boolean` + - `working_directory: optional string` - Whether this tool should be deferred and discovered via tool search. + Optional working directory to run the command in. - - `description: optional string` + - `call_id: string` - Optional description of the custom tool, used to provide more context. + The unique ID of the local shell tool call generated by the model. - - `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 local shell call. - - `Text object { type }` + - `"in_progress"` - Unconstrained free-form text. + - `"completed"` - - `type: "text"` + - `"incomplete"` - Unconstrained text format. Always `text`. + - `type: "local_shell_call"` - - `"text"` + The type of the local shell call. Always `local_shell_call`. - - `Grammar object { definition, syntax, type }` + - `"local_shell_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`. + - `LocalShellCallOutput object { id, output, type, 2 more }` - - `"lark"` + The output of a local shell tool call. - - `"regex"` + - `id: string` - - `type: "grammar"` + The unique ID of the local shell tool call generated by the model. - Grammar format. Always `grammar`. + - `output: string` - - `"grammar"` + A JSON string of the output of the local shell tool call. - - `type: "namespace"` + - `type: "local_shell_call_output"` - The type of the tool. Always `namespace`. + The type of the local shell tool call output. Always `local_shell_call_output`. - - `"namespace"` + - `"local_shell_call_output"` - - `ToolSearch object { type, description, execution, parameters }` + - `agent: optional object { agent_name }` - Hosted or BYOT tool search configuration for deferred tools. + The agent that produced this item. - - `type: "tool_search"` + - `agent_name: string` - The type of the tool. Always `tool_search`. + The canonical name of the agent that produced this item. - - `"tool_search"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `description: optional string` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - Description shown to the model for a client-executed tool search tool. + - `"in_progress"` - - `execution: optional "server" or "client"` + - `"completed"` - Whether tool search is executed by the server or by the client. + - `"incomplete"` - - `"server"` + - `ShellCall object { id, action, call_id, 6 more }` - - `"client"` + A tool call that executes one or more shell commands in a managed environment. - - `parameters: optional unknown` + - `id: string` - Parameter schema for a client-executed tool search tool. + The unique ID of the shell tool call. Populated when this item is returned via API. - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + - `action: object { commands, max_output_length, timeout_ms }` - 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 shell commands and limits that describe how to run the tool call. - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `commands: array of string` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `max_output_length: number` - - `"web_search_preview"` + Optional maximum number of characters to return from each command. - - `"web_search_preview_2025_03_11"` + - `timeout_ms: number` - - `search_content_types: optional array of "text" or "image"` + Optional timeout in milliseconds for the commands. - - `"text"` + - `call_id: string` - - `"image"` + The unique ID of the shell tool call generated by the model. - - `search_context_size: optional "low" or "medium" or "high"` + - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` - 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"` + - `BetaResponseLocalEnvironment object { type }` - - `"medium"` + Represents the use of a local environment to perform shell actions. - - `"high"` + - `type: "local"` - - `user_location: optional object { type, city, country, 2 more }` + The environment type. Always `local`. - The user's location. + - `"local"` - - `type: "approximate"` + - `BetaResponseContainerReference object { container_id, type }` - The type of location approximation. Always `approximate`. + Represents a container created with /v1/containers. - - `"approximate"` + - `container_id: string` - - `city: optional string` + - `type: "container_reference"` - Free text input for the city of the user, e.g. `San Francisco`. + The environment type. Always `container_reference`. - - `country: optional string` + - `"container_reference"` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `status: "in_progress" or "completed" or "incomplete"` - - `region: optional string` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - Free text input for the region of the user, e.g. `California`. + - `"in_progress"` - - `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 }` + - `type: "shell_call"` - Allows the assistant to create, delete, or update files using unified diffs. + The type of the item. Always `shell_call`. - - `type: "apply_patch"` + - `"shell_call"` - The type of the tool. Always `apply_patch`. + - `agent: optional object { agent_name }` - - `"apply_patch"` + 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. - - `type: "tool_search_output"` + - `Direct object { type }` - The item type. Always `tool_search_output`. + - `type: "direct"` - - `"tool_search_output"` + - `"direct"` - - `id: optional string` + - `Program object { caller_id, type }` - The unique ID of this tool search 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` + - `"program"` - The canonical name of the agent that produced this item. + - `created_by: optional string` - - `call_id: optional string` + The ID of the entity that created this tool call. - The unique ID of the tool search call generated by the model. + - `ShellCallOutput object { id, call_id, max_output_length, 6 more }` - - `execution: optional "server" or "client"` + The output of a shell tool call that was emitted. - Whether tool search was executed by the server or by the client. + - `id: string` - - `"server"` + The unique ID of the shell call output. Populated when this item is returned via API. - - `"client"` + - `call_id: string` - - `status: optional "in_progress" or "completed" or "incomplete"` + The unique ID of the shell tool call generated by the model. - The status of the tool search output. + - `max_output_length: number` - - `"in_progress"` + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - `"completed"` + - `output: array of object { outcome, stderr, stdout, created_by }` - - `"incomplete"` + An array of shell call output contents - - `AdditionalTools object { role, tools, type, 2 more }` + - `outcome: object { type } or object { exit_code, type }` - - `role: "developer"` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - The role that provided the additional tools. Only `developer` is supported. + - `Timeout object { type }` - - `"developer"` + Indicates that the shell call exceeded its configured time limit. - - `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: "timeout"` - A list of additional tools made available at this item. + The outcome type. Always `timeout`. - - `Function object { name, parameters, strict, 5 more }` + - `"timeout"` - 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). + - `Exit object { exit_code, type }` - - `name: string` + Indicates that the shell commands finished and returned an exit code. - The name of the function to call. + - `exit_code: number` - - `parameters: map[unknown]` + Exit code from the shell process. - A JSON schema object describing the parameters of the function. + - `type: "exit"` - - `strict: boolean` + The outcome type. Always `exit`. - Whether strict parameter validation is enforced for this function tool. + - `"exit"` - - `type: "function"` + - `stderr: string` - The type of the function tool. Always `function`. + The standard error output that was captured. - - `"function"` + - `stdout: string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The standard output that was captured. - The tool invocation context(s). + - `created_by: optional string` - - `"direct"` + The identifier of the actor that created the item. - - `"programmatic"` + - `status: "in_progress" or "completed" or "incomplete"` - - `defer_loading: optional boolean` + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - Whether this function is deferred and loaded via tool search. + - `"in_progress"` - - `description: optional string` + - `"completed"` - A description of the function. Used by the model to determine whether or not to call the function. + - `"incomplete"` - - `output_schema: optional map[unknown]` + - `type: "shell_call_output"` - A JSON schema object describing the JSON value encoded in string outputs for this function. + The type of the shell call output. Always `shell_call_output`. - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + - `"shell_call_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). + - `agent: optional object { agent_name }` - - `type: "file_search"` + The agent that produced this item. - The type of the file search tool. Always `file_search`. + - `agent_name: string` - - `"file_search"` + The canonical name of the agent that produced this item. - - `vector_store_ids: array of string` + - `caller: optional object { type } or object { caller_id, type }` - The IDs of the vector stores to search. + The execution context that produced this tool call. - - `filters: optional object { key, type, value } or object { filters, type }` + - `Direct object { type }` - A filter to apply. + - `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 + - `created_by: optional string` - - `"eq"` + The identifier of the actor that created the item. - - `"ne"` + - `ApplyPatchCall object { id, call_id, operation, 5 more }` - - `"gt"` + A tool call that applies file diffs by creating, deleting, or updating files. - - `"gte"` + - `id: string` - - `"lt"` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `"lte"` + - `call_id: string` - - `"in"` + The unique ID of the apply patch tool call generated by the model. - - `"nin"` + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - - `value: string or number or boolean or array of string or number` + One of the create_file, delete_file, or update_file operations applied via apply_patch. - The value to compare against the attribute key; supports string, number, or boolean types. + - `CreateFile object { diff, path, type }` - - `string` + Instruction describing how to create a file via the apply_patch tool. - - `number` + - `diff: string` - - `boolean` + Diff to apply. - - `array of string or number` + - `path: string` - - `string` + Path of the file to create. - - `number` + - `type: "create_file"` - - `CompoundFilter object { filters, type }` + Create a new file with the provided diff. - Combine multiple filters using `and` or `or`. + - `"create_file"` - - `filters: array of object { key, type, value } or unknown` + - `DeleteFile object { path, type }` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + Instruction describing how to delete a file via the apply_patch tool. - - `ComparisonFilter object { key, type, value }` + - `path: string` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + Path of the file to delete. - - `key: string` + - `type: "delete_file"` - The key to compare against the value. + Delete the specified file. - - `type: "eq" or "ne" or "gt" or 5 more` + - `"delete_file"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `UpdateFile object { diff, path, 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 + Instruction describing how to update a file via the apply_patch tool. - - `"eq"` + - `diff: string` - - `"ne"` + Diff to apply. - - `"gt"` + - `path: string` - - `"gte"` + Path of the file to update. - - `"lt"` + - `type: "update_file"` - - `"lte"` + Update an existing file with the provided diff. - - `"in"` + - `"update_file"` - - `"nin"` + - `status: "in_progress" or "completed"` - - `value: string or number or boolean or array of string or number` + The status of the apply patch tool call. One of `in_progress` or `completed`. - The value to compare against the attribute key; supports string, number, or boolean types. + - `"in_progress"` - - `string` + - `"completed"` - - `number` + - `type: "apply_patch_call"` - - `boolean` + The type of the item. Always `apply_patch_call`. - - `array of string or number` + - `"apply_patch_call"` - - `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 ID of the entity that created this tool call. - The weight of the text in the reciprocal ranking fusion. + - `ApplyPatchCallOutput object { id, call_id, status, 5 more }` - - `ranker: optional "auto" or "default-2024-11-15"` + The output emitted by an apply patch tool call. - The ranker to use for the file search. + - `id: string` - - `"auto"` + The unique ID of the apply patch tool call output. 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. + - `status: "completed" or "failed"` - - `Computer object { type }` + The status of the apply patch tool call output. One of `completed` or `failed`. - 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"` + - `"failed"` - The type of the computer tool. Always `computer`. + - `type: "apply_patch_call_output"` - - `"computer"` + The type of the item. Always `apply_patch_call_output`. - - `ComputerUsePreview object { display_height, display_width, environment, type }` + - `"apply_patch_call_output"` - 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"` + - `"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`. + - `"program"` - - `"computer_use_preview"` + - `created_by: optional string` - - `WebSearch object { type, filters, search_context_size, user_location }` + The ID of the entity that created this tool call output. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `output: optional string` - - `type: "web_search" or "web_search_2025_08_26"` + Optional textual output returned by the apply patch tool. - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `McpListTools object { id, server_label, tools, 3 more }` - - `"web_search"` + A list of tools available on an MCP server. - - `"web_search_2025_08_26"` + - `id: string` - - `filters: optional object { allowed_domains }` + The unique ID of the list. - Filters for the search. + - `server_label: string` - - `allowed_domains: optional array of string` + The label of the MCP server. - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `tools: array of object { input_schema, name, annotations, description }` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + The tools available on the server. - - `search_context_size: optional "low" or "medium" or "high"` + - `input_schema: unknown` - 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 JSON schema describing the tool's input. - - `"low"` + - `name: string` - - `"medium"` + The name of the tool. - - `"high"` + - `annotations: optional unknown` - - `user_location: optional object { city, country, region, 2 more }` + Additional annotations about the tool. - The approximate location of the user. + - `description: optional string` - - `city: optional string` + The description of the tool. - Free text input for the city of the user, e.g. `San Francisco`. + - `type: "mcp_list_tools"` - - `country: optional string` + The type of the item. Always `mcp_list_tools`. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `"mcp_list_tools"` - - `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"` + - `error: optional string` - The type of location approximation. Always `approximate`. + Error message if the server could not list tools. - - `"approximate"` + - `McpApprovalRequest object { id, arguments, name, 3 more }` - - `Mcp object { server_label, type, allowed_callers, 9 more }` + A request for human approval of a tool invocation. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `id: string` - - `server_label: string` + The unique ID of the approval request. - A label for this MCP server, used to identify it in tool calls. + - `arguments: string` - - `type: "mcp"` + A JSON string of arguments for the tool. - The type of the MCP tool. Always `mcp`. + - `name: string` - - `"mcp"` + The name of the tool to run. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `server_label: string` - The tool invocation context(s). + The label of the MCP server making the request. - - `"direct"` + - `type: "mcp_approval_request"` - - `"programmatic"` + The type of the item. Always `mcp_approval_request`. - - `allowed_tools: optional array of string or object { read_only, tool_names }` + - `"mcp_approval_request"` - 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. + - `McpApprovalResponse object { id, approval_request_id, approve, 3 more }` - - `read_only: optional boolean` + A response to an 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. + - `id: string` - - `tool_names: optional array of string` + The unique ID of the approval response - List of allowed tool names. + - `approval_request_id: string` - - `authorization: optional string` + The ID of the approval request being answered. - 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. + - `approve: boolean` - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + Whether the request was approved. - 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + - `type: "mcp_approval_response"` - Currently supported `connector_id` values are: + The type of the item. Always `mcp_approval_response`. - - 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` + - `"mcp_approval_response"` - - `"connector_dropbox"` + - `agent: optional object { agent_name }` - - `"connector_gmail"` + The agent that produced this item. - - `"connector_googlecalendar"` + - `agent_name: string` - - `"connector_googledrive"` + The canonical name of the agent that produced this item. - - `"connector_microsoftteams"` + - `reason: optional string` - - `"connector_outlookcalendar"` + Optional reason for the decision. - - `"connector_outlookemail"` + - `McpCall object { id, arguments, name, 7 more }` - - `"connector_sharepoint"` + An invocation of a tool on an MCP server. - - `defer_loading: optional boolean` + - `id: string` - Whether this MCP tool is deferred and discovered via tool search. + The unique ID of the tool call. - - `headers: optional map[string]` + - `arguments: string` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + A JSON string of the arguments passed to the tool. - - `require_approval: optional object { always, never } or "always" or "never"` + - `name: string` - Specify which of the MCP server's tools require approval. + The name of the tool that was run. - - `McpToolApprovalFilter object { always, never }` + - `server_label: 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 label of the MCP server running the tool. - - `always: optional object { read_only, tool_names }` + - `type: "mcp_call"` - A filter object to specify which tools are allowed. + The type of the item. Always `mcp_call`. - - `read_only: optional boolean` + - `"mcp_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` - - `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. + - `approval_request_id: optional string` - - `read_only: optional boolean` + 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. - 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. + - `error: optional string` - - `tool_names: optional array of string` + The error from the tool call, if any. - List of allowed tool names. + - `output: optional string` - - `McpToolApprovalSetting = "always" or "never"` + The output from 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. + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - - `"always"` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `"never"` + - `"in_progress"` - - `server_description: optional string` + - `"completed"` - Optional description of the MCP server, used to provide more context. + - `"incomplete"` - - `server_url: optional string` + - `"calling"` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `"failed"` - - `tunnel_id: optional string` + - `CustomToolCall object { id, call_id, input, 7 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. + - `id: string` - - `CodeInterpreter object { container, type, allowed_callers }` + The unique ID of the custom tool call item. - A tool that runs Python code to help generate a response to a prompt. + - `call_id: string` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + An identifier used to map this custom tool call to a tool 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. + - `input: string` - - `string` + The input for the custom tool call generated by the model. - The container ID. + - `name: string` - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + The name of the custom tool being called. - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `status: "in_progress" or "completed" or "incomplete"` - - `type: "auto"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Always `auto`. + - `"in_progress"` - - `"auto"` + - `"completed"` - - `file_ids: optional array of string` + - `"incomplete"` - An optional list of uploaded files to make available to your code. + - `type: "custom_tool_call"` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + The type of the custom tool call. Always `custom_tool_call`. - The memory limit for the code interpreter container. + - `"custom_tool_call"` - - `"1g"` + - `agent: optional object { agent_name }` - - `"4g"` + The agent that produced this item. - - `"16g"` + - `agent_name: string` - - `"64g"` + The canonical name of the agent that produced this item. - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `caller: optional object { type } or object { caller_id, type }` - Network access policy for the container. + The execution context that produced this tool call. - - `BetaContainerNetworkPolicyDisabled object { type }` + - `Direct object { type }` - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `type: "direct"` - - `type: "code_interpreter"` + - `"direct"` - The type of the code interpreter tool. Always `code_interpreter`. + - `Program object { caller_id, type }` - - `"code_interpreter"` + - `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"` + - `created_by: optional string` - - `ProgrammaticToolCalling object { type }` + The identifier of the actor that created the item. - - `type: "programmatic_tool_calling"` + - `namespace: optional string` - The type of the tool. Always `programmatic_tool_calling`. + The namespace of the custom tool being called. - - `"programmatic_tool_calling"` + - `CustomToolCallOutput object { id, call_id, output, 5 more }` - - `ImageGeneration object { type, action, background, 9 more }` + - `id: string` - A tool that generates images using the GPT image models. + The unique ID of the custom tool call output item. - - `type: "image_generation"` + - `call_id: string` - The type of the image generation tool. Always `image_generation`. + The call ID, used to map this custom tool call output to a custom tool call. - - `"image_generation"` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `action: optional "generate" or "edit" or "auto"` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - Whether to generate a new image or edit an existing image. Default: `auto`. + - `StringOutput = string` - - `"generate"` + A string of the output of the custom tool call. - - `"edit"` + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `"auto"` + Text, image, or file output of the custom tool call. - - `background: optional "transparent" or "opaque" or "auto"` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + A text input to the model. - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `"transparent"` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `"opaque"` + A file input to the model. - - `"auto"` + - `status: "in_progress" or "completed" or "incomplete"` - - `input_fidelity: optional "high" or "low"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - 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`. + - `"in_progress"` - - `"high"` + - `"completed"` - - `"low"` + - `"incomplete"` - - `input_image_mask: optional object { file_id, image_url }` + - `type: "custom_tool_call_output"` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + The type of the custom tool call output. Always `custom_tool_call_output`. - - `file_id: optional string` + - `"custom_tool_call_output"` - 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-2" or 3 more` + The canonical name of the agent that produced this item. - The image generation model to use. Default: `gpt-image-1`. + - `caller: optional object { type } or object { caller_id, type }` - - `string` + The execution context that produced this tool call. - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `Direct object { type }` - The image generation model to use. Default: `gpt-image-1`. + - `type: "direct"` - - `"gpt-image-1"` + The caller type. Always `direct`. - - `"gpt-image-1-mini"` + - `"direct"` - - `"gpt-image-2"` + - `Program object { caller_id, type }` - - `"gpt-image-2-2026-04-21"` + - `caller_id: string` - - `"gpt-image-1.5"` + The call ID of the program item that produced this tool call. - - `"chatgpt-image-latest"` + - `type: "program"` - - `moderation: optional "auto" or "low"` + The caller type. Always `program`. - Moderation level for the generated image. Default: `auto`. + - `"program"` - - `"auto"` + - `created_by: optional string` - - `"low"` + The identifier of the actor that created the item. - - `output_compression: optional number` + - `first_id: string` - Compression level for the output image. Default: 100. + The ID of the first item in the list. - - `output_format: optional "png" or "webp" or "jpeg"` + - `has_more: boolean` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + Whether there are more items available. - - `"png"` + - `last_id: string` - - `"webp"` + The ID of the last item in the list. - - `"jpeg"` + - `object: "list"` - - `partial_images: optional number` + The type of object returned, must be `list`. - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `"list"` - - `quality: optional "low" or "medium" or "high" or "auto"` +### Example - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. +```http +curl https://api.openai.com/v1/responses/$RESPONSE_ID/input_items \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - - `"low"` +#### Response - - `"medium"` +```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" +} +``` - - `"high"` +### Example - - `"auto"` +```http +curl https://api.openai.com/v1/responses/resp_abc123/input_items \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` +#### 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`. +```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 +} +``` - - `string` +## Domain Types - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` +### Beta Response Item List - 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`. +- `BetaResponseItemList object { data, first_id, has_more, 2 more }` - - `"1024x1024"` + A list of Response items. - - `"1024x1536"` + - `data: array of BetaResponseInputMessageItem or BetaResponseOutputMessage or object { id, queries, status, 3 more } or 29 more` - - `"1536x1024"` + A list of items used to generate this response. - - `"auto"` + - `BetaResponseInputMessageItem object { id, content, role, 3 more }` - - `LocalShell object { type }` + - `id: string` - A tool that allows the model to execute shell commands in a local environment. + The unique ID of the message input. - - `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"` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `Shell object { type, allowed_callers, environment }` + A text input to the model. - A tool that allows the model to execute shell commands. + - `text: string` - - `type: "shell"` + The text input to the model. - The type of the shell tool. Always `shell`. + - `type: "input_text"` - - `"shell"` + The type of the input item. Always `input_text`. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"input_text"` - 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"` - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + The breakpoint mode. Always `explicit`. - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `"explicit"` - - `BetaLocalEnvironment object { type, skills }` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `BetaContainerReference object { container_id, type }` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `Custom object { name, type, allowed_callers, 3 more }` + - `detail: "low" or "high" or "auto" or "original"` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + 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, used to identify it in tool calls. + - `"high"` - - `type: "custom"` + - `"auto"` - The type of the custom tool. Always `custom`. + - `"original"` - - `"custom"` + - `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 tool should be deferred and discovered via tool search. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `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. + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `type: "text"` + A file input to the model. - Unconstrained text format. Always `text`. + - `type: "input_file"` - - `"text"` + The type of the input item. Always `input_file`. - - `Grammar object { definition, syntax, type }` + - `"input_file"` - A grammar defined by the user. + - `detail: optional "auto" or "low" or "high"` - - `definition: 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 grammar definition. + - `"auto"` - - `syntax: "lark" or "regex"` + - `"low"` - The syntax of the grammar definition. One of `lark` or `regex`. + - `"high"` - - `"lark"` + - `file_data: optional string` - - `"regex"` + The content of the file to be sent to the model. - - `type: "grammar"` + - `file_id: optional string` - Grammar format. Always `grammar`. + The ID of the file to be sent to the model. - - `"grammar"` + - `file_url: optional string` - - `Namespace object { description, name, tools, type }` + The URL of the file to be sent to the model. - Groups function/custom tools under a shared namespace. + - `filename: optional string` - - `description: string` + The name of the file to be sent to the model. - A description of the namespace shown to the model. + - `prompt_cache_breakpoint: optional object { mode }` - - `name: string` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The namespace name used in tool calls (for example, `crm`). + - `mode: "explicit"` - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + The breakpoint mode. Always `explicit`. - The function/custom tools available inside this namespace. + - `"explicit"` - - `Function object { name, type, allowed_callers, 5 more }` + - `role: "user" or "system" or "developer"` - - `name: string` + The role of the message input. One of `user`, `system`, or `developer`. - - `type: "function"` + - `"user"` - - `"function"` + - `"system"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"developer"` - The tool invocation context(s). + - `type: "message"` - - `"direct"` + The type of the message input. Always set to `message`. - - `"programmatic"` + - `"message"` - - `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 item. One of `in_progress`, `completed`, or + `incomplete`. Populated when 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](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `BetaResponseOutputMessage object { id, content, role, 4 more }` - - `name: string` + An output message from the model. - The name of the custom tool, used to identify it in tool calls. + - `id: string` - - `type: "custom"` + The unique ID of the output message. - The type of the custom tool. Always `custom`. + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - - `"custom"` + The content of the output message. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - The tool invocation context(s). + A text output from the model. - - `"direct"` + - `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 }` - - `"programmatic"` + The annotations of the text output. - - `defer_loading: optional boolean` + - `FileCitation object { file_id, filename, index, type }` - Whether this tool should be deferred and discovered via tool search. + A citation to a file. - - `description: optional string` + - `file_id: string` - Optional description of the custom tool, used to provide more context. + The ID of the file. - - `format: optional object { type } or object { definition, syntax, type }` + - `filename: string` - The input format for the custom tool. Default is unconstrained text. + The filename of the file cited. - - `Text object { type }` + - `index: number` - Unconstrained free-form text. + The index of the file in the list of files. - - `type: "text"` + - `type: "file_citation"` - Unconstrained text format. Always `text`. + The type of the file citation. Always `file_citation`. - - `"text"` + - `"file_citation"` - - `Grammar object { definition, syntax, type }` + - `URLCitation object { end_index, start_index, title, 2 more }` - A grammar defined by the user. + A citation for a web resource used to generate a model response. - - `definition: string` + - `end_index: number` - The grammar definition. + The index of the last character of the URL citation in the message. - - `syntax: "lark" or "regex"` + - `start_index: number` - The syntax of the grammar definition. One of `lark` or `regex`. + The index of the first character of the URL citation in the message. - - `"lark"` + - `title: string` - - `"regex"` + The title of the web resource. - - `type: "grammar"` + - `type: "url_citation"` - Grammar format. Always `grammar`. + The type of the URL citation. Always `url_citation`. - - `"grammar"` + - `"url_citation"` - - `type: "namespace"` + - `url: string` - The type of the tool. Always `namespace`. + The URL of the web resource. - - `"namespace"` + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - - `ToolSearch object { type, description, execution, parameters }` + A citation for a container file used to generate a model response. - Hosted or BYOT tool search configuration for deferred tools. + - `container_id: string` - - `type: "tool_search"` + The ID of the container file. - The type of the tool. Always `tool_search`. + - `end_index: number` - - `"tool_search"` + The index of the last character of the container file citation in the message. - - `description: optional string` + - `file_id: string` - Description shown to the model for a client-executed tool search tool. + The ID of the file. - - `execution: optional "server" or "client"` + - `filename: string` - Whether tool search is executed by the server or by the client. + The filename of the container file cited. - - `"server"` + - `start_index: number` - - `"client"` + The index of the first character of the container file citation in the message. - - `parameters: optional unknown` + - `type: "container_file_citation"` - Parameter schema for a client-executed tool search tool. + The type of the container file citation. Always `container_file_citation`. - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + - `"container_file_citation"` - 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). + - `FilePath object { file_id, index, type }` - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + A path to a file. - 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"` + - `index: number` - - `search_content_types: optional array of "text" or "image"` + The index of the file in the list of files. - - `"text"` + - `type: "file_path"` - - `"image"` + The type of the file path. Always `file_path`. - - `search_context_size: optional "low" or "medium" or "high"` + - `"file_path"` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - - `"low"` + - `token: string` - - `"medium"` + - `bytes: array of number` - - `"high"` + - `logprob: number` - - `user_location: optional object { type, city, country, 2 more }` + - `top_logprobs: array of object { token, bytes, logprob }` - The user's location. + - `token: string` - - `type: "approximate"` + - `bytes: array of number` - The type of location approximation. Always `approximate`. + - `logprob: number` - - `"approximate"` + - `text: string` - - `city: optional string` + The text output from the model. - Free text input for the city of the user, e.g. `San Francisco`. + - `type: "output_text"` - - `country: optional string` + The type of the output text. Always `output_text`. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `"output_text"` - - `region: optional string` + - `BetaResponseOutputRefusal object { refusal, type }` - Free text input for the region of the user, e.g. `California`. + A refusal from the model. - - `timezone: optional string` + - `refusal: string` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The refusal explanation from the model. - - `ApplyPatch object { type, allowed_callers }` + - `type: "refusal"` - Allows the assistant to create, delete, or update files using unified diffs. + The type of the refusal. Always `refusal`. - - `type: "apply_patch"` + - `"refusal"` - The type of the tool. Always `apply_patch`. + - `role: "assistant"` - - `"apply_patch"` + 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"` - - `type: "additional_tools"` + - `"completed"` - The item type. Always `additional_tools`. + - `"incomplete"` - - `"additional_tools"` + - `type: "message"` - - `id: optional string` + The type of the output message. Always `message`. - The unique ID of this additional tools item. + - `"message"` - `agent: optional object { agent_name }` @@ -203578,36 +204003,49 @@ 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 }` + - `phase: optional "commentary" or "final_answer"` - 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](https://platform.openai.com/docs/guides/conversation-state). + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + + - `"commentary"` + + - `"final_answer"` + + - `FileSearchCall object { id, queries, status, 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 identifier of the reasoning content. + The unique ID of the file search tool call. - - `summary: array of object { text, type }` + - `queries: array of string` - Reasoning summary content. + The queries used to search for files. - - `text: string` + - `status: "in_progress" or "searching" or "completed" or 2 more` - A summary of the reasoning output from the model so far. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `type: "summary_text"` + - `"in_progress"` - The type of the object. Always `summary_text`. + - `"searching"` - - `"summary_text"` + - `"completed"` - - `type: "reasoning"` + - `"incomplete"` - The type of the object. Always `reasoning`. + - `"failed"` - - `"reasoning"` + - `type: "file_search_call"` + + The type of the file search tool call. Always `file_search_call`. + + - `"file_search_call"` - `agent: optional object { agent_name }` @@ -203617,312 +204055,321 @@ 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 }` + - `results: optional array of object { attributes, file_id, filename, 2 more }` - Reasoning text content. + The results of the file search tool call. - - `text: string` + - `attributes: optional map[string or number or boolean]` - The reasoning text from the model. + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. Keys are strings + with a maximum length of 64 characters. Values are strings with a maximum + length of 512 characters, booleans, or numbers. - - `type: "reasoning_text"` + - `string` - The type of the reasoning text. Always `reasoning_text`. + - `number` - - `"reasoning_text"` + - `boolean` - - `encrypted_content: optional string` + - `file_id: optional string` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + The unique ID of the file. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `filename: optional string` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The name of the file. - - `"in_progress"` + - `score: optional number` - - `"completed"` + The relevance score of the file - a value between 0 and 1. - - `"incomplete"` + - `text: optional string` - - `Compaction object { encrypted_content, type, id, agent }` + The text that was retrieved from the file. - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` - - `encrypted_content: string` + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - The encrypted content of the compaction summary. + - `id: string` - - `type: "compaction"` + The unique ID of the computer call. - The type of the item. Always `compaction`. + - `call_id: string` - - `"compaction"` + An identifier used when responding to the tool call with output. - - `id: optional string` + - `pending_safety_checks: array of object { id, code, message }` - The ID of the compaction item. + The pending safety checks for the computer call. - - `agent: optional object { agent_name }` + - `id: string` - The agent that produced this item. + The ID of the pending safety check. - - `agent_name: string` + - `code: optional string` - The canonical name of the agent that produced this item. + The type of the pending safety check. - - `ImageGenerationCall object { id, result, status, 2 more }` + - `message: optional string` - An image generation request made by the model. + Details about the pending safety check. - - `id: string` + - `status: "in_progress" or "completed" or "incomplete"` - The unique ID of the image generation call. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `result: string` + - `"in_progress"` - The generated image encoded in base64. + - `"completed"` - - `status: "in_progress" or "completed" or "generating" or "failed"` + - `"incomplete"` - The status of the image generation call. + - `type: "computer_call"` - - `"in_progress"` + The type of the computer call. Always `computer_call`. - - `"completed"` + - `"computer_call"` - - `"generating"` + - `action: optional BetaComputerAction` - - `"failed"` + A click action. - - `type: "image_generation_call"` + - `Click object { button, type, x, 2 more }` - The type of the image generation call. Always `image_generation_call`. + A click action. - - `"image_generation_call"` + - `button: "left" or "right" or "wheel" or 2 more` - - `agent: optional object { agent_name }` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - The agent that produced this item. + - `"left"` - - `agent_name: string` + - `"right"` - The canonical name of the agent that produced this item. + - `"wheel"` - - `CodeInterpreterCall object { id, code, container_id, 4 more }` + - `"back"` - A tool call to run code. + - `"forward"` - - `id: string` + - `type: "click"` - The unique ID of the code interpreter tool call. + Specifies the event type. For a click action, this property is always `click`. - - `code: string` + - `"click"` - The code to run, or null if not available. + - `x: number` - - `container_id: string` + The x-coordinate where the click occurred. - The ID of the container used to run the code. + - `y: number` - - `outputs: array of object { logs, type } or object { type, url }` + The y-coordinate where the click occurred. - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `keys: optional array of string` - - `Logs object { logs, type }` + The keys being held while clicking. - The logs output from the code interpreter. + - `DoubleClick object { keys, type, x, y }` - - `logs: string` + A double click action. - The logs output from the code interpreter. + - `keys: array of string` - - `type: "logs"` + The keys being held while double-clicking. - The type of the output. Always `logs`. + - `type: "double_click"` - - `"logs"` + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `Image object { type, url }` + - `"double_click"` - The image output from the code interpreter. + - `x: number` - - `type: "image"` + The x-coordinate where the double click occurred. - The type of the output. Always `image`. + - `y: number` - - `"image"` + The y-coordinate where the double click occurred. - - `url: string` + - `Drag object { path, type, keys }` - The URL of the image output from the code interpreter. + A drag action. - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + - `path: array of object { x, y }` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `"in_progress"` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `"completed"` + - `x: number` - - `"incomplete"` + The x-coordinate. - - `"interpreting"` + - `y: number` - - `"failed"` + The y-coordinate. - - `type: "code_interpreter_call"` + - `type: "drag"` - The type of the code interpreter tool call. Always `code_interpreter_call`. + Specifies the event type. For a drag action, this property is always set to `drag`. - - `"code_interpreter_call"` + - `"drag"` - - `agent: optional object { agent_name }` + - `keys: optional array of string` - The agent that produced this item. + The keys being held while dragging the mouse. - - `agent_name: string` + - `Keypress object { keys, type }` - The canonical name of the agent that produced this item. + A collection of keypresses the model would like to perform. - - `LocalShellCall object { id, action, call_id, 3 more }` + - `keys: array of string` - A tool call to run a command on the local shell. + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `id: string` + - `type: "keypress"` - The unique ID of the local shell call. + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `action: object { command, env, type, 3 more }` + - `"keypress"` - Execute a shell command on the server. + - `Move object { type, x, y, keys }` - - `command: array of string` + A mouse move action. - The command to run. + - `type: "move"` - - `env: map[string]` + Specifies the event type. For a move action, this property is always set to `move`. - Environment variables to set for the command. + - `"move"` - - `type: "exec"` + - `x: number` - The type of the local shell action. Always `exec`. + The x-coordinate to move to. - - `"exec"` + - `y: number` - - `timeout_ms: optional number` + The y-coordinate to move to. - Optional timeout in milliseconds for the command. + - `keys: optional array of string` - - `user: optional string` + The keys being held while moving the mouse. - Optional user to run the command as. + - `Screenshot object { type }` - - `working_directory: optional string` + A screenshot action. - Optional working directory to run the command in. + - `type: "screenshot"` - - `call_id: string` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - The unique ID of the local shell tool call generated by the model. + - `"screenshot"` - - `status: "in_progress" or "completed" or "incomplete"` + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - The status of the local shell call. + A scroll action. - - `"in_progress"` + - `scroll_x: number` - - `"completed"` + The horizontal scroll distance. - - `"incomplete"` + - `scroll_y: number` - - `type: "local_shell_call"` + The vertical scroll distance. - The type of the local shell call. Always `local_shell_call`. + - `type: "scroll"` - - `"local_shell_call"` + 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` - - `LocalShellCallOutput object { id, output, type, 2 more }` + The y-coordinate where the scroll occurred. - The output of a local shell tool call. + - `keys: optional array of string` - - `id: string` + The keys being held while scrolling. - The unique ID of the local shell tool call generated by the model. + - `Type object { text, type }` - - `output: string` + An action to type in text. - A JSON string of the output of the local shell tool call. + - `text: string` - - `type: "local_shell_call_output"` + The text to type. - The type of the local shell tool call output. Always `local_shell_call_output`. + - `type: "type"` - - `"local_shell_call_output"` + Specifies the event type. For a type action, this property is always set to `type`. - - `agent: optional object { agent_name }` + - `"type"` - The agent that produced this item. + - `Wait object { type }` - - `agent_name: string` + A wait action. - The canonical name of the agent that produced this item. + - `type: "wait"` - - `status: optional "in_progress" or "completed" or "incomplete"` + Specifies the event type. For a wait action, this property is always set to `wait`. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `"wait"` - - `"in_progress"` + - `actions: optional BetaComputerActionList` - - `"completed"` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `"incomplete"` + - `Click object { button, type, x, 2 more }` - - `ShellCall object { action, call_id, type, 5 more }` + A click action. - A tool representing a request to execute one or more shell commands. + - `DoubleClick object { keys, type, x, y }` - - `action: object { commands, max_output_length, timeout_ms }` + A double click action. - The shell commands and limits that describe how to run the tool call. + - `Drag object { path, type, keys }` - - `commands: array of string` + A drag action. - Ordered shell commands for the execution environment to run. + - `Keypress object { keys, type }` - - `max_output_length: optional number` + A collection of keypresses the model would like to perform. - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + - `Move object { type, x, y, keys }` - - `timeout_ms: optional number` + A mouse move action. - Maximum wall-clock time in milliseconds to allow the shell commands to run. + - `Screenshot object { type }` - - `call_id: string` + A screenshot action. - The unique ID of the shell tool call generated by the model. + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - - `type: "shell_call"` + A scroll action. - The type of the item. Always `shell_call`. + - `Type object { text, type }` - - `"shell_call"` + An action to type in text. - - `id: optional string` + - `Wait object { type }` - The unique ID of the shell tool call. Populated when this item is returned via API. + A wait action. - `agent: optional object { agent_name }` @@ -203932,105 +204379,70 @@ 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"` + - `ComputerCallOutput object { id, call_id, output, 5 more }` - The caller type. Always `direct`. + - `id: string` - - `"direct"` + The unique ID of the computer call tool output. - - `Program object { caller_id, type }` + - `call_id: string` - - `caller_id: string` + The ID of the computer tool call that produced the output. - The call ID of the program item that produced this tool call. + - `output: BetaResponseComputerToolCallOutputScreenshot` - - `type: "program"` + A computer screenshot image used with the computer use tool. - The caller type. Always `program`. + - `type: "computer_screenshot"` - - `"program"` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `environment: optional BetaLocalEnvironment or BetaContainerReference` + - `"computer_screenshot"` - The environment to execute the shell commands in. + - `file_id: optional string` - - `BetaLocalEnvironment object { type, skills }` + The identifier of an uploaded file that contains the screenshot. - - `BetaContainerReference object { container_id, type }` + - `image_url: optional string` - - `status: optional "in_progress" or "completed" or "incomplete"` + The URL of the screenshot image. - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `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"` - - `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. + - `"failed"` - - `type: "exit"` + - `"in_progress"` - The outcome type. Always `exit`. + - `type: "computer_call_output"` - - `"exit"` + The type of the computer tool call output. Always `computer_call_output`. - - `stderr: string` + - `"computer_call_output"` - Captured stderr output for the shell call. + - `acknowledged_safety_checks: optional array of object { id, code, message }` - - `stdout: string` + The safety checks reported by the API that have been acknowledged by the + developer. - Captured stdout output for the shell call. + - `id: string` - - `type: "shell_call_output"` + The ID of the pending safety check. - The type of the item. Always `shell_call_output`. + - `code: optional string` - - `"shell_call_output"` + The type of the pending safety check. - - `id: optional string` + - `message: optional string` - The unique ID of the shell tool call output. Populated when this item is returned via API. + Details about the pending safety check. - `agent: optional object { agent_name }` @@ -204040,123 +204452,105 @@ 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`. + - `created_by: optional string` - - `"program"` + The identifier of the actor that created the item. - - `max_output_length: optional number` + - `WebSearchCall object { id, action, status, 2 more }` - The maximum number of UTF-8 characters captured for this shell call's combined output. + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `id: string` - The status of the shell call output. + The unique ID of the web search tool call. - - `"in_progress"` + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - - `"completed"` + 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). - - `"incomplete"` + - `Search object { type, queries, query, sources }` - - `ApplyPatchCall object { call_id, operation, status, 4 more }` + Action type "search" - Performs a web search query. - A tool call representing a request to create, delete, or update files using diff patches. + - `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` - The specific create, delete, or update instruction for the apply_patch tool call. + The search queries. - - `CreateFile object { diff, path, type }` + - `query: optional string` - Instruction for creating a new file via the apply_patch tool. + The search query. - - `diff: string` + - `sources: optional array of object { type, url }` - Unified diff content to apply when creating the file. + The sources used in the search. - - `path: string` + - `type: "url"` - Path of the file to create relative to the workspace root. + The type of source. Always `url`. - - `type: "create_file"` + - `"url"` - The operation type. Always `create_file`. + - `url: string` - - `"create_file"` + The URL of the source. - - `DeleteFile object { path, type }` + - `OpenPage object { type, url }` - Instruction for deleting an existing 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 relative to the workspace root. + The action type. - - `type: "delete_file"` + - `"open_page"` - The operation type. Always `delete_file`. + - `url: optional string` - - `"delete_file"` + The URL opened by the model. - - `UpdateFile object { diff, path, type }` + - `FindInPage object { pattern, type, url }` - Instruction for updating an existing file via the apply_patch tool. + Action type "find_in_page": Searches for a pattern within a loaded page. - - `diff: string` + - `pattern: string` - Unified diff content to apply to the existing file. + The pattern or text to search for within the page. - - `path: string` + - `type: "find_in_page"` - Path of the file to update relative to the workspace root. + The action type. - - `type: "update_file"` + - `"find_in_page"` - The operation type. Always `update_file`. + - `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"` - - `"completed"` + - `"searching"` - - `type: "apply_patch_call"` + - `"completed"` - 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 }` @@ -204166,55 +204560,40 @@ 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 }` + - `FunctionCall object { id, arguments, call_id, 7 more }` - - `caller_id: string` + - `id: string` - The call ID of the program item that produced this tool call. + The unique ID of the function tool call. - - `type: "program"` + - `arguments: string` - The caller type. Always `program`. + A JSON string of the arguments to pass to the function. - - `"program"` + - `call_id: string` - - `ApplyPatchCallOutput object { call_id, status, type, 4 more }` + The unique ID of the function tool call generated by the model. - The streamed output emitted by an apply patch tool call. + - `name: string` - - `call_id: string` + The name of the function to run. - The unique ID of the apply patch tool call generated by the model. + - `status: "in_progress" or "completed" or "incomplete"` - - `status: "completed" or "failed"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The status of the apply patch tool call output. One of `completed` or `failed`. + - `"in_progress"` - `"completed"` - - `"failed"` - - - `type: "apply_patch_call_output"` - - The type of the item. Always `apply_patch_call_output`. + - `"incomplete"` - - `"apply_patch_call_output"` + - `type: "function_call"` - - `id: optional string` + The type of the function tool call. Always `function_call`. - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `"function_call"` - `agent: optional object { agent_name }` @@ -204232,8 +204611,6 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "direct"` - The caller type. Always `direct`. - - `"direct"` - `Program object { caller_id, type }` @@ -204244,51 +204621,67 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "program"` - The caller type. Always `program`. - - `"program"` - - `output: optional string` + - `created_by: optional string` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + The identifier of the actor that created the item. - - `McpListTools object { id, server_label, tools, 3 more }` + - `namespace: optional string` - A list of tools available on an MCP server. + The namespace of the function to run. + + - `FunctionCallOutput object { id, call_id, output, 5 more }` - `id: string` - The unique ID of the list. + The unique ID of the function call tool output. - - `server_label: string` + - `call_id: string` - The label of the MCP server. + The unique ID of the function tool call generated by the model. - - `tools: array of object { input_schema, name, annotations, description }` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - The tools available on the server. + The output from the function call generated by your code. + Can be a string or an list of output content. - - `input_schema: unknown` + - `StringOutput = string` - The JSON schema describing the tool's input. + A string of the output of the function call. - - `name: string` + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - The name of the tool. + Text, image, or file output of the function call. - - `annotations: optional unknown` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - Additional annotations about the tool. + A text input to the model. - - `description: optional string` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - The description of the tool. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `type: "mcp_list_tools"` + - `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: "function_call_output"` - The type of the item. Always `mcp_list_tools`. + The type of the function tool call output. Always `function_call_output`. - - `"mcp_list_tools"` + - `"function_call_output"` - `agent: optional object { agent_name }` @@ -204298,181 +204691,169 @@ curl -X POST https://api.openai.com/v1/responses/compact \ 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. + - `caller: optional object { type } or object { caller_id, type }` - - `arguments: string` + The execution context that produced this tool call. - A JSON string of arguments for the tool. + - `Direct object { type }` - - `name: string` + - `type: "direct"` - The name of the tool to run. + The caller type. Always `direct`. - - `server_label: string` + - `"direct"` - The label of the MCP server making the request. + - `Program object { caller_id, type }` - - `type: "mcp_approval_request"` + - `caller_id: string` - The type of the item. Always `mcp_approval_request`. + The call ID of the program item that produced this tool call. - - `"mcp_approval_request"` + - `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. - - `McpApprovalResponse object { approval_request_id, approve, type, 3 more }` + - `AgentMessage object { id, author, content, 3 more }` - A response to an MCP approval request. + - `id: string` - - `approval_request_id: string` + The unique ID of the agent message. - The ID of the approval request being answered. + - `author: string` - - `approve: boolean` + The sending agent identity. - Whether the request was approved. + - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` - - `type: "mcp_approval_response"` + Encrypted content sent between agents. - The type of the item. Always `mcp_approval_response`. + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `"mcp_approval_response"` + A text input to the model. - - `id: optional string` + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - The unique ID of the approval response + A text output from the model. - - `agent: optional object { agent_name }` + - `Text object { text, type }` - The agent that produced this item. + A text content. - - `agent_name: string` + - `text: string` - The canonical name of the agent that produced this item. + - `type: "text"` - - `reason: optional string` + - `"text"` - Optional reason for the decision. + - `SummaryText object { text, type }` - - `McpCall object { id, arguments, name, 7 more }` + A summary text from the model. - An invocation of a tool on an MCP server. + - `text: string` - - `id: string` + A summary of the reasoning output from the model so far. - The unique ID of the tool call. + - `type: "summary_text"` - - `arguments: string` + The type of the object. Always `summary_text`. - A JSON string of the arguments passed to the tool. + - `"summary_text"` - - `name: string` + - `ReasoningText object { text, type }` - The name of the tool that was run. + Reasoning text from the model. - - `server_label: string` + - `text: string` - The label of the MCP server running the tool. + The reasoning text from the model. - - `type: "mcp_call"` + - `type: "reasoning_text"` - The type of the item. Always `mcp_call`. + The type of the reasoning text. Always `reasoning_text`. - - `"mcp_call"` + - `"reasoning_text"` - - `agent: optional object { agent_name }` + - `BetaResponseOutputRefusal object { refusal, type }` - The agent that produced this item. + A refusal from 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). - - `approval_request_id: optional string` + - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + A screenshot of a computer. - - `error: optional string` + - `detail: "low" or "high" or "auto" or "original"` - The error from the tool call, if any. + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `output: optional string` + - `"low"` - The output from the tool call. + - `"high"` - - `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`. + - `"original"` - - `"in_progress"` + - `file_id: string` - - `"completed"` + The identifier of an uploaded file that contains the screenshot. - - `"incomplete"` + - `image_url: string` - - `"calling"` + The URL of the screenshot image. - - `"failed"` + - `type: "computer_screenshot"` - - `CustomToolCallOutput object { call_id, output, type, 3 more }` + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - The output of a custom tool call from your code, being sent back to the model. + - `"computer_screenshot"` - - `call_id: string` + - `prompt_cache_breakpoint: optional object { mode }` - The call ID, used to map this custom tool call output to a custom 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. - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `mode: "explicit"` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + The breakpoint mode. Always `explicit`. - - `StringOutput = string` + - `"explicit"` - A string of the output of the custom tool call. + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + A file input to the model. - Text, image, or file output of the custom tool call. + - `EncryptedContent object { encrypted_content, type }` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - A text input to the model. + - `encrypted_content: string` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + Opaque encrypted content. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `type: "encrypted_content"` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + The type of the input item. Always `encrypted_content`. - A file input to the model. + - `"encrypted_content"` - - `type: "custom_tool_call_output"` + - `recipient: string` - The type of the custom tool call output. Always `custom_tool_call_output`. + The destination agent identity. - - `"custom_tool_call_output"` + - `type: "agent_message"` - - `id: optional string` + The type of the item. Always `agent_message`. - The unique ID of the custom tool call output in the OpenAI platform. + - `"agent_message"` - `agent: optional object { agent_name }` @@ -204482,55 +204863,41 @@ 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. + - `MultiAgentCall object { id, action, arguments, 3 more }` - - `Direct object { type }` + - `id: string` - - `type: "direct"` + The unique ID of the multi-agent call item. - The caller type. Always `direct`. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `"direct"` + The multi-agent action to execute. - - `Program object { caller_id, type }` + - `"spawn_agent"` - - `caller_id: string` + - `"interrupt_agent"` - The call ID of the program item that produced this tool call. + - `"list_agents"` - - `type: "program"` + - `"send_message"` - The caller type. Always `program`. + - `"followup_task"` - - `"program"` + - `"wait_agent"` - - `CustomToolCall object { call_id, input, name, 5 more }` + - `arguments: string` - A call to a custom tool created by the model. + The JSON string of arguments generated for the action. - `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`. + The unique ID linking this call to its output. - - `"custom_tool_call"` + - `type: "multi_agent_call"` - - `id: optional string` + The type of the multi-agent call. Always `multi_agent_call`. - The unique ID of the custom tool call in the OpenAI platform. + - `"multi_agent_call"` - `agent: optional object { agent_name }` @@ -204540,55 +204907,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 }` + - `MultiAgentCallOutput object { id, action, call_id, 3 more }` - The execution context that produced this tool call. + - `id: string` - - `Direct object { type }` + The unique ID of the multi-agent call output item. - - `type: "direct"` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `"direct"` + The multi-agent action that produced this result. - - `Program object { caller_id, type }` + - `"spawn_agent"` - - `caller_id: string` + - `"interrupt_agent"` - The call ID of the program item that produced this tool call. + - `"list_agents"` - - `type: "program"` + - `"send_message"` - - `"program"` + - `"followup_task"` - - `namespace: optional string` + - `"wait_agent"` - The namespace of the custom tool being called. + - `call_id: string` - - `CompactionTrigger object { type, agent }` + The unique ID of the multi-agent call. - Compacts the current context. Must be the final input item. + - `output: array of BetaResponseOutputText` - - `type: "compaction_trigger"` + Text output returned by the multi-agent action. - The type of the item. Always `compaction_trigger`. + - `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 }` - - `"compaction_trigger"` + The annotations of the text output. - - `agent: optional object { agent_name }` + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - The agent that produced this item. + - `text: string` - - `agent_name: string` + The text output from the model. - The canonical name of the agent that produced this item. + - `type: "output_text"` - - `ItemReference object { id, agent, type }` + The type of the output text. Always `output_text`. - An internal identifier for an item to reference. + - `type: "multi_agent_call_output"` - - `id: string` + The type of the multi-agent result. Always `multi_agent_call_output`. - The ID of the item to reference. + - `"multi_agent_call_output"` - `agent: optional object { agent_name }` @@ -204598,35 +204965,43 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `type: optional "item_reference"` - - The type of item to reference. Always `item_reference`. + - `ToolSearchCall object { id, arguments, call_id, 5 more }` - - `"item_reference"` + - `id: string` - - `Program object { id, call_id, code, 3 more }` + The unique ID of the tool search call item. - - `id: string` + - `arguments: unknown` - The unique ID of this program item. + Arguments used for the tool search call. - `call_id: string` - The stable call ID of the program item. + The unique ID of the tool search call generated by the model. - - `code: string` + - `execution: "server" or "client"` - The JavaScript source executed by programmatic tool calling. + Whether tool search was executed by the server or by the client. - - `fingerprint: string` + - `"server"` - Opaque program replay fingerprint that must be round-tripped. + - `"client"` - - `type: "program"` + - `status: "in_progress" or "completed" or "incomplete"` - The item type. Always `program`. + The status of the tool search call item that was recorded. - - `"program"` + - `"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 }` @@ -204636,1161 +205011,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 }` + - `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 this program output item. + The unique ID of the tool search output item. - `call_id: string` - The call ID of the program item. + The unique ID of the tool search call generated by the model. - - `result: string` + - `execution: "server" or "client"` - The result produced by the program item. + Whether tool search was executed by the server or by the client. - - `status: "completed" or "incomplete"` + - `"server"` - The terminal status of the program output. + - `"client"` + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the tool search output item that was recorded. + + - `"in_progress"` - `"completed"` - `"incomplete"` - - `type: "program_output"` + - `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 item type. Always `program_output`. + The loaded tool definitions returned by tool search. - - `"program_output"` + - `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]` - - `metadata: map[string]` + A JSON schema object describing the parameters of the 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. + - `strict: boolean` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + Whether strict parameter validation is enforced for this function tool. - - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` + - `type: "function"` - 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](https://platform.openai.com/docs/models) - to browse and compare available models. + The type of the function tool. Always `function`. - - `"gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more` + - `"function"` - 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](https://platform.openai.com/docs/models) - to browse and compare available models. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"gpt-5.6-sol"` + The tool invocation context(s). - - `"gpt-5.6-terra"` + - `"direct"` - - `"gpt-5.6-luna"` + - `"programmatic"` - - `"gpt-5.4"` + - `defer_loading: optional boolean` - - `"gpt-5.4-mini"` + Whether this function is deferred and loaded via tool search. - - `"gpt-5.4-nano"` + - `description: optional string` - - `"gpt-5.4-mini-2026-03-17"` + A description of the function. Used by the model to determine whether or not to call the function. - - `"gpt-5.4-nano-2026-03-17"` + - `output_schema: optional map[unknown]` - - `"gpt-5.3-chat-latest"` + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `"gpt-5.2"` + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - - `"gpt-5.2-2025-12-11"` + 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-5.2-chat-latest"` + - `type: "file_search"` - - `"gpt-5.2-pro"` + The type of the file search tool. Always `file_search`. - - `"gpt-5.2-pro-2025-12-11"` + - `"file_search"` - - `"gpt-5.1"` + - `vector_store_ids: array of string` - - `"gpt-5.1-2025-11-13"` + The IDs of the vector stores to search. - - `"gpt-5.1-codex"` + - `filters: optional object { key, type, value } or object { filters, type }` - - `"gpt-5.1-mini"` + A filter to apply. - - `"gpt-5.1-chat-latest"` + - `ComparisonFilter object { key, type, value }` - - `"gpt-5"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `"gpt-5-mini"` + - `key: string` - - `"gpt-5-nano"` + The key to compare against the value. - - `"gpt-5-2025-08-07"` + - `type: "eq" or "ne" or "gt" or 5 more` - - `"gpt-5-mini-2025-08-07"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `"gpt-5-nano-2025-08-07"` + - `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-chat-latest"` + - `"eq"` - - `"gpt-4.1"` + - `"ne"` - - `"gpt-4.1-mini"` + - `"gt"` - - `"gpt-4.1-nano"` + - `"gte"` - - `"gpt-4.1-2025-04-14"` + - `"lt"` - - `"gpt-4.1-mini-2025-04-14"` + - `"lte"` - - `"gpt-4.1-nano-2025-04-14"` + - `"in"` - - `"o4-mini"` + - `"nin"` - - `"o4-mini-2025-04-16"` + - `value: string or number or boolean or array of string or number` - - `"o3"` + The value to compare against the attribute key; supports string, number, or boolean types. - - `"o3-2025-04-16"` + - `string` - - `"o3-mini"` + - `number` - - `"o3-mini-2025-01-31"` + - `boolean` - - `"o1"` + - `array of string or number` - - `"o1-2024-12-17"` + - `string` - - `"o1-preview"` + - `number` - - `"o1-preview-2024-09-12"` + - `CompoundFilter object { filters, type }` - - `"o1-mini"` + Combine multiple filters using `and` or `or`. - - `"o1-mini-2024-09-12"` + - `filters: array of object { key, type, value } or unknown` - - `"gpt-4o"` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `"gpt-4o-2024-11-20"` + - `ComparisonFilter object { key, type, value }` - - `"gpt-4o-2024-08-06"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `"gpt-4o-2024-05-13"` + - `key: string` - - `"gpt-4o-audio-preview"` + The key to compare against the value. - - `"gpt-4o-audio-preview-2024-10-01"` + - `type: "eq" or "ne" or "gt" or 5 more` - - `"gpt-4o-audio-preview-2024-12-17"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `"gpt-4o-audio-preview-2025-06-03"` + - `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-4o-mini-audio-preview"` + - `"eq"` - - `"gpt-4o-mini-audio-preview-2024-12-17"` + - `"ne"` - - `"gpt-4o-search-preview"` + - `"gt"` - - `"gpt-4o-mini-search-preview"` + - `"gte"` - - `"gpt-4o-search-preview-2025-03-11"` + - `"lt"` - - `"gpt-4o-mini-search-preview-2025-03-11"` + - `"lte"` - - `"chatgpt-4o-latest"` + - `"in"` - - `"codex-mini-latest"` + - `"nin"` - - `"gpt-4o-mini"` + - `value: string or number or boolean or array of string or number` - - `"gpt-4o-mini-2024-07-18"` + The value to compare against the attribute key; supports string, number, or boolean types. - - `"gpt-4-turbo"` + - `string` - - `"gpt-4-turbo-2024-04-09"` + - `number` - - `"gpt-4-0125-preview"` + - `boolean` - - `"gpt-4-turbo-preview"` + - `array of string or number` - - `"gpt-4-1106-preview"` + - `string` - - `"gpt-4-vision-preview"` + - `number` - - `"gpt-4"` + - `unknown` - - `"gpt-4-0314"` + - `type: "and" or "or"` - - `"gpt-4-0613"` + Type of operation: `and` or `or`. - - `"gpt-4-32k"` + - `"and"` - - `"gpt-4-32k-0314"` + - `"or"` - - `"gpt-4-32k-0613"` + - `max_num_results: optional number` - - `"gpt-3.5-turbo"` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `"gpt-3.5-turbo-16k"` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `"gpt-3.5-turbo-0301"` + Ranking options for search. - - `"gpt-3.5-turbo-0613"` + - `hybrid_search: optional object { embedding_weight, text_weight }` - - `"gpt-3.5-turbo-1106"` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `"gpt-3.5-turbo-0125"` + - `embedding_weight: number` - - `"gpt-3.5-turbo-16k-0613"` + The weight of the embedding in the reciprocal ranking fusion. - - `"o1-pro"` + - `text_weight: number` - - `"o1-pro-2025-03-19"` + The weight of the text in the reciprocal ranking fusion. - - `"o3-pro"` + - `ranker: optional "auto" or "default-2024-11-15"` - - `"o3-pro-2025-06-10"` + The ranker to use for the file search. - - `"o3-deep-research"` + - `"auto"` - - `"o3-deep-research-2025-06-26"` + - `"default-2024-11-15"` - - `"o4-mini-deep-research"` + - `score_threshold: optional number` - - `"o4-mini-deep-research-2025-06-26"` + 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-use-preview"` + - `Computer object { type }` - - `"computer-use-preview-2025-03-11"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"gpt-5-codex"` + - `type: "computer"` - - `"gpt-5-pro"` + The type of the computer tool. Always `computer`. - - `"gpt-5-pro-2025-10-06"` + - `"computer"` - - `"gpt-5.1-codex-max"` + - `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). - - `object: "response"` + - `display_height: number` - The object type of this resource - always set to `response`. + The height of the computer display. - - `"response"` + - `display_width: number` - - `output: array of BetaResponseOutputItem` + The width of the computer display. - An array of content items generated by the model. + - `environment: "windows" or "mac" or "linux" or 2 more` - - 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 type of computer environment to control. - - `BetaResponseOutputMessage object { id, content, role, 4 more }` + - `"windows"` - An output message from the model. + - `"mac"` - - `FileSearchCall object { id, queries, status, 3 more }` + - `"linux"` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `"ubuntu"` - - `id: string` + - `"browser"` - The unique ID of the file search tool call. + - `type: "computer_use_preview"` - - `queries: array of string` + The type of the computer use tool. Always `computer_use_preview`. - The queries used to search for files. + - `"computer_use_preview"` - - `status: "in_progress" or "searching" or "completed" or 2 more` + - `WebSearch object { type, filters, search_context_size, user_location }` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - - `"in_progress"` + - `type: "web_search" or "web_search_2025_08_26"` - - `"searching"` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `"completed"` + - `"web_search"` - - `"incomplete"` + - `"web_search_2025_08_26"` - - `"failed"` + - `filters: optional object { allowed_domains }` - - `type: "file_search_call"` + Filters for the search. - The type of the file search tool call. Always `file_search_call`. + - `allowed_domains: optional array of string` - - `"file_search_call"` + 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"` - - `results: optional array of object { attributes, file_id, filename, 2 more }` + - `"medium"` - The results of the file search tool call. + - `"high"` - - `attributes: optional map[string or number or boolean]` + - `user_location: optional object { city, country, region, 2 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. + The approximate location of the user. - - `string` + - `city: optional string` - - `number` + Free text input for the city of the user, e.g. `San Francisco`. - - `boolean` + - `country: optional string` - - `file_id: optional string` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The unique ID of the file. + - `region: optional string` - - `filename: optional string` + Free text input for the region of the user, e.g. `California`. - The name of the file. + - `timezone: optional string` - - `score: optional number` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The relevance score of the file - a value between 0 and 1. + - `type: optional "approximate"` - - `text: optional string` + The type of location approximation. Always `approximate`. - The text that was retrieved from the file. + - `"approximate"` - - `FunctionCall object { arguments, call_id, name, 6 more }` + - `Mcp object { server_label, type, allowed_callers, 9 more }` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) 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). - - `arguments: string` + - `server_label: string` - A JSON string of the arguments to pass to the function. + 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`. - - `name: string` + - `"mcp"` - The name of the function to run. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `type: "function_call"` + The tool invocation context(s). - The type of the function tool call. Always `function_call`. + - `"direct"` - - `"function_call"` + - `"programmatic"` - - `id: optional string` + - `allowed_tools: optional array of string or object { read_only, tool_names }` - The unique ID of the function tool call. + 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` - - `namespace: optional string` + - `"connector_dropbox"` - The namespace of the function to run. + - `"connector_gmail"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"connector_googlecalendar"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"connector_googledrive"` - - `"in_progress"` + - `"connector_microsoftteams"` - - `"completed"` + - `"connector_outlookcalendar"` - - `"incomplete"` + - `"connector_outlookemail"` - - `FunctionCallOutput object { id, call_id, output, 5 more }` + - `"connector_sharepoint"` - - `id: string` + - `defer_loading: optional boolean` - The unique ID of the function call tool output. + Whether this MCP tool is deferred and discovered via tool search. - - `call_id: string` + - `headers: optional map[string]` - The unique ID of the function tool call generated by the model. + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `require_approval: optional object { always, never } or "always" or "never"` - The output from the function call generated by your code. - Can be a string or an list of output content. + Specify which of the MCP server's tools require approval. - - `StringOutput = string` + - `McpToolApprovalFilter object { always, never }` - A string of the output of the function 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. - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `always: optional object { read_only, tool_names }` - Text, image, or file output of the function call. + 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. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `tool_names: optional array of string` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + List of allowed tool names. - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `never: optional object { read_only, tool_names }` - A file input to the model. + A filter object to specify which tools are allowed. - - `status: "in_progress" or "completed" or "incomplete"` + - `read_only: optional boolean` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `"in_progress"` + - `tool_names: optional array of string` - - `"completed"` + List of allowed tool names. - - `"incomplete"` + - `McpToolApprovalSetting = "always" or "never"` - - `type: "function_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 function tool call output. Always `function_call_output`. + - `"always"` - - `"function_call_output"` + - `"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. - - `caller: optional object { type } or object { caller_id, type }` + - `tunnel_id: optional string` - The execution context 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. - - `Direct object { type }` + - `CodeInterpreter object { container, type, allowed_callers }` - - `type: "direct"` + A tool that runs Python code to help generate a response to a prompt. - The caller type. Always `direct`. + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `"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. - - `Program object { caller_id, type }` + - `string` - - `caller_id: string` + The container ID. - The call ID of the program item that produced this tool call. + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - - `type: "program"` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - The caller type. Always `program`. + - `type: "auto"` - - `"program"` + Always `auto`. - - `created_by: optional string` + - `"auto"` - The identifier of the actor that created the item. + - `file_ids: optional array of string` - - `AgentMessage object { id, author, content, 3 more }` + An optional list of uploaded files to make available to your code. - - `id: string` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - The unique ID of the agent message. + The memory limit for the code interpreter container. - - `author: string` + - `"1g"` - The sending agent identity. + - `"4g"` - - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` + - `"16g"` - Encrypted content sent between agents. + - `"64g"` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - A text input to the model. + Network access policy for the container. - - `BetaResponseOutputText object { annotations, text, type, logprobs }` + - `BetaContainerNetworkPolicyDisabled object { type }` - A text output from the model. + - `type: "disabled"` - - `Text object { text, type }` + Disable outbound network access. Always `disabled`. - A text content. + - `"disabled"` - - `text: string` + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `type: "text"` + - `allowed_domains: array of string` - - `"text"` + A list of allowed domains when type is `allowlist`. - - `SummaryText object { text, type }` + - `type: "allowlist"` - A summary text from the model. + Allow outbound network access only to specified domains. Always `allowlist`. - - `text: string` + - `"allowlist"` - A summary of the reasoning output from the model so far. + - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` - - `type: "summary_text"` + Optional domain-scoped secrets for allowlisted domains. - The type of the object. Always `summary_text`. + - `domain: string` - - `"summary_text"` + The domain associated with the secret. - - `ReasoningText object { text, type }` + - `name: string` - Reasoning text from the model. + The name of the secret to inject for the domain. - - `text: string` + - `value: string` - The reasoning text from the model. + The secret value to inject for the domain. - - `type: "reasoning_text"` + - `type: "code_interpreter"` - The type of the reasoning text. Always `reasoning_text`. + The type of the code interpreter tool. Always `code_interpreter`. - - `"reasoning_text"` + - `"code_interpreter"` - - `BetaResponseOutputRefusal object { refusal, type }` + - `allowed_callers: optional array of "direct" or "programmatic"` - A refusal from the model. + The tool invocation context(s). - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `"direct"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `"programmatic"` - - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` + - `ProgrammaticToolCalling object { type }` - A screenshot of a computer. + - `type: "programmatic_tool_calling"` - - `detail: "low" or "high" or "auto" or "original"` + The type of the tool. Always `programmatic_tool_calling`. - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `"programmatic_tool_calling"` - - `"low"` + - `ImageGeneration object { type, action, background, 9 more }` - - `"high"` + A tool that generates images using the GPT image models. - - `"auto"` + - `type: "image_generation"` - - `"original"` + The type of the image generation tool. Always `image_generation`. - - `file_id: string` + - `"image_generation"` - The identifier of an uploaded file that contains the screenshot. + - `action: optional "generate" or "edit" or "auto"` - - `image_url: string` + Whether to generate a new image or edit an existing image. Default: `auto`. - The URL of the screenshot image. + - `"generate"` - - `type: "computer_screenshot"` + - `"edit"` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + - `"auto"` - - `"computer_screenshot"` + - `background: optional "transparent" or "opaque" or "auto"` - - `prompt_cache_breakpoint: optional object { mode }` + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `"transparent"` - - `mode: "explicit"` + - `"opaque"` - The breakpoint mode. Always `explicit`. + - `"auto"` - - `"explicit"` + - `input_fidelity: optional "high" or "low"` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - A file input to the model. + - `"high"` - - `EncryptedContent object { encrypted_content, type }` + - `"low"` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `input_image_mask: optional object { file_id, image_url }` - - `encrypted_content: string` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - Opaque encrypted content. + - `file_id: optional string` - - `type: "encrypted_content"` + File ID for the mask image. - The type of the input item. Always `encrypted_content`. + - `image_url: optional string` - - `"encrypted_content"` + Base64-encoded mask image. - - `recipient: string` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - The destination agent identity. + The image generation model to use. Default: `gpt-image-1`. - - `type: "agent_message"` + - `string` - The type of the item. Always `agent_message`. + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `"agent_message"` + The image generation model to use. Default: `gpt-image-1`. - - `agent: optional object { agent_name }` + - `"gpt-image-1"` - The agent that produced this item. + - `"gpt-image-1-mini"` - - `agent_name: string` + - `"gpt-image-1.5"` - The canonical name of the agent that produced this item. + - `moderation: optional "auto" or "low"` - - `MultiAgentCall object { id, action, arguments, 3 more }` + Moderation level for the generated image. Default: `auto`. - - `id: string` + - `"auto"` - The unique ID of the multi-agent call item. + - `"low"` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `output_compression: optional number` - The multi-agent action to execute. + Compression level for the output image. Default: 100. - - `"spawn_agent"` + - `output_format: optional "png" or "webp" or "jpeg"` - - `"interrupt_agent"` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `"list_agents"` + - `"png"` - - `"send_message"` + - `"webp"` - - `"followup_task"` + - `"jpeg"` - - `"wait_agent"` + - `partial_images: optional number` - - `arguments: string` + 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`. - The JSON string of arguments generated for the action. + - `"low"` - - `call_id: string` + - `"medium"` - The unique ID linking this call to its output. + - `"high"` - - `type: "multi_agent_call"` + - `"auto"` - The type of the multi-agent call. Always `multi_agent_call`. + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `"multi_agent_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 }` + - `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"` - - `MultiAgentCallOutput object { id, action, call_id, 3 more }` + - `"1024x1536"` - - `id: string` + - `"1536x1024"` - The unique ID of the multi-agent call output item. + - `"auto"` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `LocalShell object { type }` - The multi-agent action that produced this result. + 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"` - - `call_id: string` + The type of the shell tool. Always `shell`. - The unique ID of the multi-agent call. + - `"shell"` - - `output: array of BetaResponseOutputText` + - `allowed_callers: optional array of "direct" or "programmatic"` - Text output returned by the multi-agent action. + The tool invocation context(s). - - `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 }` + - `"direct"` - The annotations of the text output. + - `"programmatic"` - - `text: string` + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - The text output from the model. + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - - `type: "output_text"` + - `type: "container_auto"` - The type of the output text. Always `output_text`. + Automatically creates a container for this request - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + - `"container_auto"` - - `type: "multi_agent_call_output"` + - `file_ids: optional array of string` - The type of the multi-agent result. Always `multi_agent_call_output`. + An optional list of uploaded files to make available to your code. - - `"multi_agent_call_output"` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `agent: optional object { agent_name }` + The memory limit for the container. - The agent that produced this item. + - `"1g"` - - `agent_name: string` + - `"4g"` - The canonical name of the agent that produced this item. + - `"16g"` - - `WebSearchCall object { id, action, status, 2 more }` + - `"64g"` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `id: string` + Network access policy for the container. - The unique ID of the web search tool call. + - `BetaContainerNetworkPolicyDisabled object { type }` - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - 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). + - `skills: optional array of BetaSkillReference or BetaInlineSkill` - - `Search object { type, queries, query, sources }` + An optional list of skills referenced by id or inline data. - Action type "search" - Performs a web search query. + - `BetaSkillReference object { skill_id, type, version }` - - `type: "search"` + - `skill_id: string` - The action type. + The ID of the referenced skill. - - `"search"` + - `type: "skill_reference"` - - `queries: optional array of string` + References a skill created with the /v1/skills endpoint. - The search queries. + - `"skill_reference"` - - `query: optional string` + - `version: optional string` - The search query. + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `sources: optional array of object { type, url }` + - `BetaInlineSkill object { description, name, source, type }` - The sources used in the search. + - `description: string` - - `type: "url"` + The description of the skill. - The type of source. Always `url`. + - `name: string` - - `"url"` + The name of the skill. - - `url: string` + - `source: BetaInlineSkillSource` - The URL of the source. + Inline skill payload - - `OpenPage object { type, url }` + - `data: string` - Action type "open_page" - Opens a specific URL from search results. + Base64-encoded skill zip bundle. - - `type: "open_page"` + - `media_type: "application/zip"` - The action type. + The media type of the inline skill payload. Must be `application/zip`. - - `"open_page"` + - `"application/zip"` - - `url: optional string` + - `type: "base64"` - The URL opened by the model. + The type of the inline skill source. Must be `base64`. - - `FindInPage object { pattern, type, url }` + - `"base64"` - Action type "find_in_page": Searches for a pattern within a loaded page. + - `type: "inline"` - - `pattern: string` + Defines an inline skill for this request. - The pattern or text to search for within the page. + - `"inline"` - - `type: "find_in_page"` + - `BetaLocalEnvironment object { type, skills }` - The action type. + - `type: "local"` - - `"find_in_page"` + Use a local computer environment. - - `url: string` + - `"local"` - The URL of the page searched for the pattern. + - `skills: optional array of BetaLocalSkill` - - `status: "in_progress" or "searching" or "completed" or "failed"` + An optional list of skills. - The status of the web search tool call. + - `description: string` - - `"in_progress"` + The description of the skill. - - `"searching"` + - `name: string` - - `"completed"` + The name of the skill. - - `"failed"` + - `path: string` - - `type: "web_search_call"` + The path to the directory containing the skill. - The type of the web search tool call. Always `web_search_call`. + - `BetaContainerReference object { container_id, type }` - - `"web_search_call"` + - `container_id: string` - - `agent: optional object { agent_name }` + The ID of the referenced container. - The agent that produced this item. + - `type: "container_reference"` - - `agent_name: string` + References a container created with the /v1/containers endpoint - The canonical name of the agent that produced this item. + - `"container_reference"` - - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` + - `Custom object { name, type, allowed_callers, 3 more }` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + 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 computer call. + The name of the custom tool, used to identify it in tool calls. - - `call_id: string` + - `type: "custom"` - An identifier used when responding to the tool call with output. + The type of the custom tool. Always `custom`. - - `pending_safety_checks: array of object { id, code, message }` + - `"custom"` - The pending safety checks for the computer call. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `id: string` + The tool invocation context(s). - The ID of the pending safety check. + - `"direct"` - - `code: optional string` + - `"programmatic"` - The type of the pending safety check. + - `defer_loading: optional boolean` - - `message: optional string` + Whether this tool should be deferred and discovered via tool search. - Details about the pending safety check. + - `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: "computer_call"` + - `type: "text"` - The type of the computer call. Always `computer_call`. + Unconstrained text format. Always `text`. - - `"computer_call"` + - `"text"` - - `action: optional BetaComputerAction` + - `Grammar object { definition, syntax, type }` - A click action. + A grammar defined by the user. - - `actions: optional BetaComputerActionList` + - `definition: string` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + 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"` - - `ComputerCallOutput object { id, call_id, output, 5 more }` + - `type: "grammar"` - - `id: string` + Grammar format. Always `grammar`. - The unique ID of the computer call tool output. + - `"grammar"` - - `call_id: string` + - `Namespace object { description, name, tools, type }` - The ID of the computer tool call that produced the output. + Groups function/custom tools under a shared namespace. - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `description: string` - A computer screenshot image used with the computer use tool. + A description of the namespace shown to the model. - - `status: "completed" or "incomplete" or "failed" or "in_progress"` + - `name: string` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + The namespace name used in tool calls (for example, `crm`). - - `"completed"` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - - `"incomplete"` + The function/custom tools available inside this namespace. - - `"failed"` + - `Function object { name, type, allowed_callers, 5 more }` - - `"in_progress"` + - `name: string` - - `type: "computer_call_output"` + - `type: "function"` - The type of the computer tool call output. Always `computer_call_output`. + - `"function"` - - `"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. + - `defer_loading: optional boolean` - - `code: optional string` + Whether this function should be deferred and discovered via tool search. - The type of the pending safety check. + - `description: optional string` - - `message: optional string` + - `output_schema: optional map[unknown]` - Details about 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. - - `agent: optional object { agent_name }` + - `parameters: optional unknown` - The agent that produced this item. + - `strict: optional boolean` - - `agent_name: 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 canonical name of the agent that produced this item. + - `Custom object { name, type, allowed_callers, 3 more }` - - `created_by: optional string` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - The identifier of the actor that created the item. + - `name: string` - - `Reasoning object { id, summary, type, 4 more }` + The name of the custom tool, used to identify it in tool calls. - 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](https://platform.openai.com/docs/guides/conversation-state). + - `type: "custom"` - - `id: string` + The type of the custom tool. Always `custom`. - The unique identifier of the reasoning content. + - `"custom"` - - `summary: array of object { text, type }` + - `allowed_callers: optional array of "direct" or "programmatic"` - Reasoning summary content. + The tool invocation context(s). - - `text: string` + - `"direct"` - A summary of the reasoning output from the model so far. + - `"programmatic"` - - `type: "summary_text"` + - `defer_loading: optional boolean` - The type of the object. Always `summary_text`. + Whether this tool should be deferred and discovered via tool search. - - `"summary_text"` + - `description: optional string` - - `type: "reasoning"` + Optional description of the custom tool, used to provide more context. - The type of the object. Always `reasoning`. + - `format: optional object { type } or object { definition, syntax, type }` - - `"reasoning"` + 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`. - - `content: optional array of object { text, type }` + - `"text"` - Reasoning text content. + - `Grammar object { definition, syntax, type }` - - `text: string` + A grammar defined by the user. - The reasoning text from the model. + - `definition: string` - - `type: "reasoning_text"` + The grammar definition. - The type of the reasoning text. Always `reasoning_text`. + - `syntax: "lark" or "regex"` - - `"reasoning_text"` + The syntax of the grammar definition. One of `lark` or `regex`. - - `encrypted_content: optional string` + - `"lark"` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `"regex"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `type: "grammar"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Grammar format. Always `grammar`. - - `"in_progress"` + - `"grammar"` - - `"completed"` + - `type: "namespace"` - - `"incomplete"` + The type of the tool. Always `namespace`. - - `Program object { id, call_id, code, 3 more }` + - `"namespace"` - - `id: string` + - `ToolSearch object { type, description, execution, parameters }` - The unique ID of the program item. + Hosted or BYOT tool search configuration for deferred tools. - - `call_id: string` + - `type: "tool_search"` - The stable call ID of the program item. + The type of the tool. Always `tool_search`. - - `code: string` + - `"tool_search"` - The JavaScript source executed by programmatic tool calling. + - `description: optional string` - - `fingerprint: string` + Description shown to the model for a client-executed tool search tool. - Opaque program replay fingerprint that must be round-tripped. + - `execution: optional "server" or "client"` - - `type: "program"` + Whether tool search is executed by the server or by the client. - The type of the item. Always `program`. + - `"server"` - - `"program"` + - `"client"` - - `agent: optional object { agent_name }` + - `parameters: optional unknown` - The agent that produced this item. + Parameter schema for a client-executed tool search tool. - - `agent_name: string` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - The canonical name of 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). - - `ProgramOutput object { id, call_id, result, 3 more }` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `id: string` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - The unique ID of the program output item. + - `"web_search_preview"` - - `call_id: string` + - `"web_search_preview_2025_03_11"` - The call ID of the program item. + - `search_content_types: optional array of "text" or "image"` - - `result: string` + - `"text"` - The result produced by the program item. + - `"image"` - - `status: "completed" or "incomplete"` + - `search_context_size: optional "low" or "medium" or "high"` - The terminal status of the program output 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. - - `"completed"` + - `"low"` - - `"incomplete"` + - `"medium"` - - `type: "program_output"` + - `"high"` - The type of the item. Always `program_output`. + - `user_location: optional object { type, city, country, 2 more }` - - `"program_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` - - `ToolSearchCall object { id, arguments, call_id, 5 more }` + Free text input for the city of the user, e.g. `San Francisco`. - - `id: string` + - `country: optional string` - The unique ID of the tool search call item. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `arguments: unknown` + - `region: optional string` - Arguments used for the tool search call. + Free text input for the region of the user, e.g. `California`. - - `call_id: string` + - `timezone: optional string` - The unique ID of the tool search call generated by the model. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `execution: "server" or "client"` + - `ApplyPatch object { type, allowed_callers }` - Whether tool search was executed by the server or by the client. + Allows the assistant to create, delete, or update files using unified diffs. - - `"server"` + - `type: "apply_patch"` - - `"client"` + The type of the tool. Always `apply_patch`. - - `status: "in_progress" or "completed" or "incomplete"` + - `"apply_patch"` - The status of the tool search call item that was recorded. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"in_progress"` + The tool invocation context(s). - - `"completed"` + - `"direct"` - - `"incomplete"` + - `"programmatic"` - - `type: "tool_search_call"` + - `type: "tool_search_output"` - The type of the item. Always `tool_search_call`. + The type of the item. Always `tool_search_output`. - - `"tool_search_call"` + - `"tool_search_output"` - `agent: optional object { agent_name }` @@ -205804,37 +206204,35 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The identifier of the actor that created the item. - - `ToolSearchOutput object { id, call_id, execution, 5 more }` + - `AdditionalTools object { id, role, tools, 2 more }` - `id: string` - The unique ID of the tool search output item. - - - `call_id: string` + The unique ID of the additional tools item. - The unique ID of the tool search call generated by the model. + - `role: "unknown" or "user" or "assistant" or 5 more` - - `execution: "server" or "client"` + The role that provided the additional tools. - Whether tool search was executed by the server or by the client. + - `"unknown"` - - `"server"` + - `"user"` - - `"client"` + - `"assistant"` - - `status: "in_progress" or "completed" or "incomplete"` + - `"system"` - The status of the tool search output item that was recorded. + - `"critic"` - - `"in_progress"` + - `"discriminator"` - - `"completed"` + - `"developer"` - - `"incomplete"` + - `"tool"` - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - The loaded tool definitions returned by tool search. + The additional tool definitions made available at this item. - `Function object { name, parameters, strict, 5 more }` @@ -206097,7 +206495,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-web-search). + [web search tool](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -206157,7 +206555,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -206209,7 +206607,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -206401,19 +206799,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `background: optional "transparent" or "opaque" or "auto"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. - - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. - - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - `"transparent"` @@ -206442,13 +206829,13 @@ curl -X POST https://api.openai.com/v1/responses/compact \ Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `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-2" or 3 more` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` The image generation model to use. Default: `gpt-image-1`. @@ -206456,14 +206843,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"gpt-image-1-mini"` - - `"gpt-image-2"` - - - `"gpt-image-2-2026-04-21"` - - `"gpt-image-1.5"` - - `"chatgpt-image-latest"` - - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -206560,7 +206941,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -206674,7 +207055,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -206806,1127 +207187,1610 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The type of location approximation. Always `approximate`. - - `"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. + + - `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 - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `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. + + - `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"` - - `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`. + - `"program"` - - `timezone: optional string` + - `created_by: optional string` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The ID of the entity that created this tool call. - - `ApplyPatch object { type, allowed_callers }` + - `ShellCallOutput object { id, call_id, max_output_length, 6 more }` - Allows the assistant to create, delete, or update files using unified diffs. + The output of a shell tool call that was emitted. - - `type: "apply_patch"` + - `id: string` - The type of the tool. Always `apply_patch`. + The unique ID of the shell call output. Populated when this item is returned via API. - - `"apply_patch"` + - `call_id: string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The unique ID of the shell tool call generated by the model. - The tool invocation context(s). + - `max_output_length: number` - - `"direct"` + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - `"programmatic"` + - `output: array of object { outcome, stderr, stdout, created_by }` - - `type: "tool_search_output"` + An array of shell call output contents - The type of the item. Always `tool_search_output`. + - `outcome: object { type } or object { exit_code, type }` - - `"tool_search_output"` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - - `agent: optional object { agent_name }` + - `Timeout object { type }` - The agent that produced this item. + Indicates that the shell call exceeded its configured time limit. - - `agent_name: string` + - `type: "timeout"` - The canonical name of the agent that produced this item. + The outcome type. Always `timeout`. - - `created_by: optional string` + - `"timeout"` - The identifier of the actor that created the item. + - `Exit object { exit_code, type }` - - `AdditionalTools object { id, role, tools, 2 more }` + Indicates that the shell commands finished and returned an exit code. - - `id: string` + - `exit_code: number` - The unique ID of the additional tools item. + Exit code from the shell process. - - `role: "unknown" or "user" or "assistant" or 5 more` + - `type: "exit"` - The role that provided the additional tools. + The outcome type. Always `exit`. - - `"unknown"` + - `"exit"` - - `"user"` + - `stderr: string` - - `"assistant"` + The standard error output that was captured. - - `"system"` + - `stdout: string` - - `"critic"` + The standard output that was captured. - - `"discriminator"` + - `created_by: optional string` - - `"developer"` + The identifier of the actor that created the item. - - `"tool"` + - `status: "in_progress" or "completed" or "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 status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - The additional tool definitions made available at this item. + - `"in_progress"` - - `Function object { name, parameters, strict, 5 more }` + - `"completed"` - 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). + - `"incomplete"` - - `name: string` + - `type: "shell_call_output"` - The name of the function to call. + The type of the shell call output. Always `shell_call_output`. - - `parameters: map[unknown]` + - `"shell_call_output"` - A JSON schema object describing the parameters of the function. + - `agent: optional object { agent_name }` - - `strict: boolean` + The agent that produced this item. - 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`. + - `caller: optional object { type } or object { caller_id, type }` - - `"function"` + 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 function is deferred and loaded via tool search. + The call ID of the program item that produced this tool call. - - `description: optional string` + - `type: "program"` - A description of the function. Used by the model to determine whether or not to call the function. + - `"program"` - - `output_schema: optional map[unknown]` + - `created_by: optional string` - A JSON schema object describing the JSON value encoded in string outputs for this function. + The identifier of the actor that created the item. - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + - `ApplyPatchCall object { id, call_id, operation, 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 that applies file diffs by creating, deleting, or updating files. - - `type: "file_search"` + - `id: string` - The type of the file search tool. Always `file_search`. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `"file_search"` + - `call_id: string` - - `vector_store_ids: array of string` + The unique ID of the apply patch tool call generated by the model. - The IDs of the vector stores to search. + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - - `filters: optional object { key, type, value } or object { filters, type }` + One of the create_file, delete_file, or update_file operations applied via apply_patch. - A filter to apply. + - `CreateFile object { diff, path, type }` - - `ComparisonFilter object { key, type, value }` + Instruction describing how to create a file via the apply_patch tool. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `diff: string` - - `key: string` + Diff to apply. - The key to compare against the value. + - `path: string` - - `type: "eq" or "ne" or "gt" or 5 more` + Path of the file to create. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `type: "create_file"` - - `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 + Create a new file with the provided diff. - - `"eq"` + - `"create_file"` - - `"ne"` + - `DeleteFile object { path, type }` - - `"gt"` + Instruction describing how to delete a file via the apply_patch tool. - - `"gte"` + - `path: string` - - `"lt"` + Path of the file to delete. - - `"lte"` + - `type: "delete_file"` - - `"in"` + Delete the specified file. - - `"nin"` + - `"delete_file"` - - `value: string or number or boolean or array of string or number` + - `UpdateFile object { diff, path, type }` - The value to compare against the attribute key; supports string, number, or boolean types. + Instruction describing how to update a file via the apply_patch tool. - - `string` + - `diff: string` - - `number` + Diff to apply. - - `boolean` + - `path: string` - - `array of string or number` + Path of the file to update. - - `string` + - `type: "update_file"` - - `number` + Update an existing file with the provided diff. - - `CompoundFilter object { filters, type }` + - `"update_file"` - Combine multiple filters using `and` or `or`. + - `status: "in_progress" or "completed"` - - `filters: array of object { key, type, value } or unknown` + The status of the apply patch tool call. One of `in_progress` or `completed`. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `"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. + - `type: "apply_patch_call"` - - `key: string` + The type of the item. Always `apply_patch_call`. - The key to compare against the value. + - `"apply_patch_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"` + - `caller: optional object { type } or object { caller_id, type }` - - `"gt"` + The execution context that produced this tool call. - - `"gte"` + - `Direct object { type }` - - `"lt"` + - `type: "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` + - `"program"` - - `number` + - `created_by: optional string` - - `boolean` + The ID of the entity that created this tool call. - - `array of string or number` + - `ApplyPatchCallOutput object { id, call_id, status, 5 more }` - - `string` + The output emitted by an apply patch tool call. - - `number` + - `id: string` - - `unknown` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `type: "and" or "or"` + - `call_id: string` - Type of operation: `and` or `or`. + The unique ID of the apply patch tool call generated by the model. - - `"and"` + - `status: "completed" or "failed"` - - `"or"` + The status of the apply patch tool call output. One of `completed` or `failed`. - - `max_num_results: optional number` + - `"completed"` - 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: "apply_patch_call_output"` - Ranking options for search. + The type of the item. Always `apply_patch_call_output`. - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `"apply_patch_call_output"` - 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. + - `caller: optional object { type } or object { caller_id, type }` - - `ranker: optional "auto" or "default-2024-11-15"` + The execution context that produced this tool call. - The ranker to use for the file search. + - `Direct object { type }` - - `"auto"` + - `type: "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"` + - `"program"` - The type of the computer tool. Always `computer`. + - `created_by: optional string` - - `"computer"` + The ID of the entity that created this tool call output. - - `ComputerUsePreview object { display_height, display_width, environment, type }` + - `output: 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 textual output returned by the apply patch tool. - - `display_height: number` + - `McpListTools object { id, server_label, tools, 3 more }` - The height of the computer display. + A list of tools available on an MCP server. - - `display_width: number` + - `id: string` - The width of the computer display. + The unique ID of the list. - - `environment: "windows" or "mac" or "linux" or 2 more` + - `server_label: string` - The type of computer environment to control. + The label of the MCP server. - - `"windows"` + - `tools: array of object { input_schema, name, annotations, description }` - - `"mac"` + The tools available on the server. - - `"linux"` + - `input_schema: unknown` - - `"ubuntu"` + The JSON schema describing the tool's input. - - `"browser"` + - `name: string` - - `type: "computer_use_preview"` + The name of the tool. - The type of the computer use tool. Always `computer_use_preview`. + - `annotations: optional unknown` - - `"computer_use_preview"` + Additional annotations about the tool. - - `WebSearch object { type, filters, search_context_size, user_location }` + - `description: optional string` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The description of the tool. - - `type: "web_search" or "web_search_2025_08_26"` + - `type: "mcp_list_tools"` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + The type of the item. Always `mcp_list_tools`. - - `"web_search"` + - `"mcp_list_tools"` - - `"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. + - `error: optional string` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + Error message if the server could not list tools. - - `search_context_size: optional "low" or "medium" or "high"` + - `McpApprovalRequest object { id, arguments, name, 3 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. + A request for human approval of a tool invocation. - - `"low"` + - `id: string` - - `"medium"` + The unique ID of the approval request. - - `"high"` + - `arguments: string` - - `user_location: optional object { city, country, region, 2 more }` + A JSON string of arguments for the tool. - The approximate location of the user. + - `name: string` - - `city: optional string` + The name of the tool to run. - Free text input for the city of the user, e.g. `San Francisco`. + - `server_label: string` - - `country: optional string` + The label of the MCP server making the request. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `type: "mcp_approval_request"` - - `region: optional string` + The type of the item. Always `mcp_approval_request`. - Free text input for the region of the user, e.g. `California`. + - `"mcp_approval_request"` - - `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. - - `type: optional "approximate"` + - `agent_name: string` - The type of location approximation. Always `approximate`. + The canonical name of the agent that produced this item. - - `"approximate"` + - `McpApprovalResponse object { id, approval_request_id, approve, 3 more }` - - `Mcp object { server_label, type, allowed_callers, 9 more }` + A response to an MCP approval request. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `id: string` - - `server_label: string` + The unique ID of the approval response - A label for this MCP server, used to identify it in tool calls. + - `approval_request_id: string` - - `type: "mcp"` + The ID of the approval request being answered. - The type of the MCP tool. Always `mcp`. + - `approve: boolean` - - `"mcp"` + Whether the request was approved. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `type: "mcp_approval_response"` - The tool invocation context(s). + The type of the item. Always `mcp_approval_response`. - - `"direct"` + - `"mcp_approval_response"` - - `"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 + - `reason: optional string` - - `McpToolFilter object { read_only, tool_names }` + Optional reason for the decision. - A filter object to specify which tools are allowed. + - `McpCall object { id, arguments, name, 7 more }` - - `read_only: optional boolean` + An invocation of a tool on an 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. + - `id: string` - - `tool_names: optional array of string` + The unique ID of the tool call. - List of allowed tool names. + - `arguments: string` - - `authorization: optional string` + A JSON string of the arguments passed to 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. + - `name: string` - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + The name of the tool that was run. - 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + - `server_label: string` - Currently supported `connector_id` values are: + The label of the MCP server running 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_call"` - - `"connector_dropbox"` + The type of the item. Always `mcp_call`. - - `"connector_gmail"` + - `"mcp_call"` - - `"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"` + - `approval_request_id: optional string` - - `"connector_sharepoint"` + 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. - - `defer_loading: optional boolean` + - `error: optional string` - Whether this MCP tool is deferred and discovered via tool search. + The error from the tool call, if any. - - `headers: optional map[string]` + - `output: optional string` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + The output from the tool call. - - `require_approval: optional object { always, never } or "always" or "never"` + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - Specify which of the MCP server's tools require approval. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `McpToolApprovalFilter object { always, never }` + - `"in_progress"` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `"completed"` - - `always: optional object { read_only, tool_names }` + - `"incomplete"` - A filter object to specify which tools are allowed. + - `"calling"` - - `read_only: optional boolean` + - `"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. + - `CustomToolCall object { id, call_id, input, 7 more }` - - `tool_names: optional array of string` + - `id: string` - List of allowed tool names. + The unique ID of the custom tool call item. - - `never: optional object { read_only, tool_names }` + - `call_id: string` - A filter object to specify which tools are allowed. + An identifier used to map this custom tool call to a tool call output. - - `read_only: optional boolean` + - `input: 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 input for the custom tool call generated by the model. - - `tool_names: optional array of string` + - `name: string` - List of allowed tool names. + The name of the custom tool being called. - - `McpToolApprovalSetting = "always" or "never"` + - `status: "in_progress" or "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. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"always"` + - `"in_progress"` - - `"never"` + - `"completed"` - - `server_description: optional string` + - `"incomplete"` - Optional description of the MCP server, used to provide more context. + - `type: "custom_tool_call"` - - `server_url: optional string` + The type of the custom tool call. Always `custom_tool_call`. - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `"custom_tool_call"` - - `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 }` + - `caller: optional object { type } or object { caller_id, type }` - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + The execution context that produced this tool call. - - `string` + - `Direct object { type }` - The container ID. + - `type: "direct"` - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + - `"direct"` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `Program object { caller_id, type }` - - `type: "auto"` + - `caller_id: string` - Always `auto`. + The call ID of the program item that produced this tool call. - - `"auto"` + - `type: "program"` - - `file_ids: optional array of string` + - `"program"` - An optional list of uploaded files to make available to your code. + - `created_by: optional string` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + The identifier of the actor that created the item. - The memory limit for the code interpreter container. + - `namespace: optional string` - - `"1g"` + The namespace of the custom tool being called. - - `"4g"` + - `CustomToolCallOutput object { id, call_id, output, 5 more }` - - `"16g"` + - `id: string` - - `"64g"` + The unique ID of the custom tool call output item. - - `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"` + - `status: "in_progress" or "completed" or "incomplete"` - - `ImageGeneration object { type, action, background, 9 more }` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - A tool that generates images using the GPT image models. + - `"in_progress"` - - `type: "image_generation"` + - `"completed"` - The type of the image generation tool. Always `image_generation`. + - `"incomplete"` - - `"image_generation"` + - `type: "custom_tool_call_output"` - - `action: optional "generate" or "edit" or "auto"` + The type of the custom tool call output. Always `custom_tool_call_output`. - Whether to generate a new image or edit an existing image. Default: `auto`. + - `"custom_tool_call_output"` - - `"generate"` + - `agent: optional object { agent_name }` - - `"edit"` + The agent that produced this item. - - `"auto"` + - `agent_name: string` - - `background: optional "transparent" or "opaque" or "auto"` + The canonical name of the agent that produced this item. - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + - `caller: optional object { type } or object { caller_id, type }` - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + The execution context that produced this tool call. - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `Direct object { type }` - - `"transparent"` + - `type: "direct"` - - `"opaque"` + The caller type. Always `direct`. - - `"auto"` + - `"direct"` - - `input_fidelity: optional "high" or "low"` + - `Program 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`. + - `caller_id: string` - - `"high"` + The call ID of the program item that produced this tool call. - - `"low"` + - `type: "program"` - - `input_image_mask: optional object { file_id, image_url }` + The caller type. Always `program`. - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `"program"` - - `file_id: optional string` + - `created_by: optional string` - File ID for the mask image. + The identifier of the actor that created the item. - - `image_url: optional string` + - `first_id: string` - Base64-encoded mask image. + The ID of the first item in the list. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `has_more: boolean` - The image generation model to use. Default: `gpt-image-1`. + Whether there are more items available. - - `string` + - `last_id: string` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + The ID of the last item in the list. - The image generation model to use. Default: `gpt-image-1`. + - `object: "list"` - - `"gpt-image-1"` + The type of object returned, must be `list`. - - `"gpt-image-1-mini"` + - `"list"` - - `"gpt-image-2"` +# Input Tokens - - `"gpt-image-2-2026-04-21"` +## Get input token counts - - `"gpt-image-1.5"` +**post** `/responses/input_tokens?beta=true` - - `"chatgpt-image-latest"` +Returns input token counts of the request. - - `moderation: optional "auto" or "low"` +Returns an object with `object` set to `response.input_tokens` and an `input_tokens` count. - Moderation level for the generated image. Default: `auto`. +### Header Parameters - - `"auto"` +- `"openai-beta": optional array of "responses_multi_agent=v1"` - - `"low"` + - `"responses_multi_agent=v1"` - - `output_compression: optional number` +### Body Parameters - Compression level for the output image. Default: 100. +- `conversation: optional string or BetaResponseConversationParam` - - `output_format: optional "png" or "webp" or "jpeg"` + 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. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `ConversationID = string` - - `"png"` + The unique ID of the conversation. - - `"webp"` + - `BetaResponseConversationParam object { id }` - - `"jpeg"` + The conversation that this response belongs to. - - `partial_images: optional number` + - `id: string` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + The unique ID of the conversation. - - `quality: optional "low" or "medium" or "high" or "auto"` +- `input: optional string or array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + Text, image, or file inputs to the model, used to generate a response - - `"low"` + - `string` - - `"medium"` + A text input to the model, equivalent to a text input with the `user` role. - - `"high"` + - `array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` - - `"auto"` + A list of one or many input items to the model, containing different content types. - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `BetaEasyInputMessage object { content, role, phase, type }` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + A 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. - - `string` + - `content: string or BetaResponseInputMessageContentList` - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - 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`. + - `TextInput = string` - - `"1024x1024"` + A text input to the model. - - `"1024x1536"` + - `BetaResponseInputMessageContentList = array of BetaResponseInputContent` - - `"1536x1024"` + A list of one or many input items to the model, containing different content + types. - - `"auto"` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `LocalShell object { type }` + A text input to the model. - A tool that allows the model to execute shell commands in a local environment. + - `text: string` - - `type: "local_shell"` + The text input to the model. - The type of the local shell tool. Always `local_shell`. + - `type: "input_text"` - - `"local_shell"` + The type of the input item. Always `input_text`. - - `Shell object { type, allowed_callers, environment }` + - `"input_text"` - A tool that allows the model to execute shell commands. + - `prompt_cache_breakpoint: optional object { mode }` - - `type: "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. - The type of the shell tool. Always `shell`. + - `mode: "explicit"` - - `"shell"` + The breakpoint mode. Always `explicit`. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"explicit"` - The tool invocation context(s). + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `"direct"` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `"programmatic"` + - `detail: "low" or "high" or "auto" or "original"` - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `"low"` - - `BetaLocalEnvironment object { type, skills }` + - `"high"` - - `BetaContainerReference object { container_id, type }` + - `"auto"` - - `Custom object { name, type, allowed_callers, 3 more }` + - `"original"` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `type: "input_image"` - - `name: string` + The type of the input item. Always `input_image`. - The name of the custom tool, used to identify it in tool calls. + - `"input_image"` - - `type: "custom"` + - `file_id: optional string` - The type of the custom tool. Always `custom`. + The ID of the file to be sent to the model. - - `"custom"` + - `image_url: optional string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - 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"` - - `defer_loading: optional boolean` + The breakpoint mode. Always `explicit`. - Whether this tool should be deferred and discovered via tool search. + - `"explicit"` - - `description: optional string` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - Optional description of the custom tool, used to provide more context. + A file input to the model. - - `format: optional object { type } or object { definition, syntax, type }` + - `type: "input_file"` - The input format for the custom tool. Default is unconstrained text. + The type of the input item. Always `input_file`. - - `Text object { type }` + - `"input_file"` - Unconstrained free-form text. + - `detail: optional "auto" or "low" or "high"` - - `type: "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`. - Unconstrained text format. Always `text`. + - `"auto"` - - `"text"` + - `"low"` - - `Grammar object { definition, syntax, type }` + - `"high"` - A grammar defined by the user. + - `file_data: optional string` - - `definition: string` + The content of the file to be sent to the model. - The grammar definition. + - `file_id: optional string` - - `syntax: "lark" or "regex"` + The ID of the file to be sent to the model. - The syntax of the grammar definition. One of `lark` or `regex`. + - `file_url: optional string` - - `"lark"` + The URL of the file to be sent to the model. - - `"regex"` + - `filename: optional string` - - `type: "grammar"` + The name of the file to be sent to the model. - Grammar format. Always `grammar`. + - `prompt_cache_breakpoint: optional object { mode }` - - `"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. - - `Namespace object { description, name, tools, type }` + - `mode: "explicit"` - Groups function/custom tools under a shared namespace. + The breakpoint mode. Always `explicit`. - - `description: string` + - `"explicit"` - A description of the namespace shown to the model. + - `role: "user" or "assistant" or "system" or "developer"` - - `name: string` + The role of the message input. One of `user`, `assistant`, `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 }` + - `"assistant"` - The function/custom tools available inside this namespace. + - `"system"` - - `Function object { name, type, allowed_callers, 5 more }` + - `"developer"` - - `name: string` + - `phase: optional "commentary" or "final_answer"` - - `type: "function"` + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - `"function"` + - `"commentary"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"final_answer"` - The tool invocation context(s). + - `type: optional "message"` - - `"direct"` + The type of the message input. Always `message`. - - `"programmatic"` + - `"message"` - - `defer_loading: optional boolean` + - `Message object { content, role, agent, 2 more }` - Whether this function should be deferred and discovered via tool search. + 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. - - `description: optional string` + - `content: BetaResponseInputMessageContentList` - - `output_schema: optional map[unknown]` + A list of one or many input items to the model, containing different content + types. - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `role: "user" or "system" or "developer"` - - `parameters: optional unknown` + The role of the message input. One of `user`, `system`, or `developer`. - - `strict: optional boolean` + - `"user"` - 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. + - `"system"` - - `Custom object { name, type, allowed_callers, 3 more }` + - `"developer"` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `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`. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"custom"` + The status of 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: optional "message"` - - `defer_loading: optional boolean` + The type of the message input. Always set to `message`. - Whether this tool should be deferred and discovered via tool search. + - `"message"` - - `description: optional string` + - `BetaResponseOutputMessage object { id, content, role, 4 more }` - Optional description of the custom tool, used to provide more context. + An output message from the model. - - `format: optional object { type } or object { definition, syntax, type }` + - `id: string` - The input format for the custom tool. Default is unconstrained text. + The unique ID of the output message. - - `Text object { type }` + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - Unconstrained free-form text. + The content of the output message. - - `type: "text"` + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - Unconstrained text format. Always `text`. + A text output from the model. - - `"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 }` - - `Grammar object { definition, syntax, type }` + The annotations of the text output. - A grammar defined by the user. + - `FileCitation object { file_id, filename, index, type }` - - `definition: string` + A citation to a file. - The grammar definition. + - `file_id: string` - - `syntax: "lark" or "regex"` + The ID of the file. - The syntax of the grammar definition. One of `lark` or `regex`. + - `filename: string` - - `"lark"` + The filename of the file cited. - - `"regex"` + - `index: number` - - `type: "grammar"` + The index of the file in the list of files. - Grammar format. Always `grammar`. + - `type: "file_citation"` - - `"grammar"` + The type of the file citation. Always `file_citation`. - - `type: "namespace"` + - `"file_citation"` - The type of the tool. Always `namespace`. + - `URLCitation object { end_index, start_index, title, 2 more }` - - `"namespace"` + A citation for a web resource used to generate a model response. - - `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 URL citation in the message. - - `type: "tool_search"` + - `start_index: number` - The type of the tool. Always `tool_search`. + The index of the first character of the URL citation in the message. - - `"tool_search"` + - `title: string` - - `description: optional string` + The title of the web resource. - Description shown to the model for a client-executed tool search tool. + - `type: "url_citation"` - - `execution: optional "server" or "client"` + The type of the URL citation. Always `url_citation`. - Whether tool search is executed by the server or by the client. + - `"url_citation"` - - `"server"` + - `url: string` - - `"client"` + The URL of the web resource. - - `parameters: optional unknown` + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - Parameter schema for a client-executed tool search tool. + A citation for a container file used to generate a model response. - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + - `container_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 container file. - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `end_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 last character of the container file citation in the message. - - `"web_search_preview"` + - `file_id: string` - - `"web_search_preview_2025_03_11"` + The ID of the file. - - `search_content_types: optional array of "text" or "image"` + - `filename: string` + + 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](https://platform.openai.com/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 }` @@ -207936,39 +208800,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 }` @@ -207978,58 +208852,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"` @@ -208037,301 +208926,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 }` @@ -208341,109 +209237,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 }` @@ -208453,55 +209351,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 }` @@ -208531,180 +209406,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 }` @@ -208714,354 +209569,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](https://platform.openai.com/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 array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` - - `"auto"` + Citations associated with the text content. - - `"required"` + - `array of 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. + - `array of 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](https://platform.openai.com/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](https://platform.openai.com/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"` + - `array of 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](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/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](https://platform.openai.com/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](https://platform.openai.com/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 }` @@ -209324,7 +210146,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-web-search). + [web search tool](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -209384,7 +210206,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -209436,7 +210258,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -209582,8 +210404,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`. @@ -209628,19 +210482,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `background: optional "transparent" or "opaque" or "auto"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. - - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. - - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - `"transparent"` @@ -209669,13 +210512,13 @@ curl -X POST https://api.openai.com/v1/responses/compact \ Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `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-2" or 3 more` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` The image generation model to use. Default: `gpt-image-1`. @@ -209683,14 +210526,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"gpt-image-1-mini"` - - `"gpt-image-2"` - - - `"gpt-image-2-2026-04-21"` - - `"gpt-image-1.5"` - - `"chatgpt-image-latest"` - - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -209781,13 +210618,131 @@ 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](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -209901,7 +210856,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -210069,2267 +211024,1776 @@ 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` - - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/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](https://platform.openai.com/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"` - - - `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](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. - - - `prompt: optional BetaResponsePrompt` - - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/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](https://platform.openai.com/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](https://platform.openai.com/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](https://platform.openai.com/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. - 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"` + - `type: "tool_search_output"` - - `"detailed"` + The item type. Always `tool_search_output`. - - `safety_identifier: optional string` + - `"tool_search_output"` - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `id: optional string` - - `service_tier: optional "auto" or "default" or "flex" or 2 more` + The unique ID of this tool search output. - Specifies the processing type used for serving the request. + - `agent: optional object { agent_name }` - - 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](https://platform.openai.com/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 agent that produced this item. - 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. + - `agent_name: string` - - `"auto"` + The canonical name of the agent that produced this item. - - `"default"` + - `call_id: optional string` - - `"flex"` + The unique ID of the tool search call generated by the model. - - `"scale"` + - `execution: optional "server" or "client"` - - `"priority"` + Whether tool search was executed by the server or by the client. - - `status: optional BetaResponseStatus` + - `"server"` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + - `"client"` - - `"completed"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"failed"` + The status of the tool search output. - `"in_progress"` - - `"cancelled"` - - - `"queued"` + - `"completed"` - `"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](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/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](https://platform.openai.com/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. + - `AdditionalTools object { role, tools, type, 2 more }` - - `Text object { type }` + - `role: "developer"` - Default response format. Used to generate text responses. + The role that provided the additional tools. Only `developer` is supported. - - `type: "text"` + - `"developer"` - The type of response format being defined. Always `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` - - `"text"` + A list of additional tools made available at this item. - - `BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` + - `Function object { name, parameters, strict, 5 more }` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + 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 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](https://platform.openai.com/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`. - - - `"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](https://platform.openai.com/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](https://platform.openai.com/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. - - - `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` - - The ID of the output item that the content part was added to. - - - `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. + The name of the function to call. - - `BetaResponseOutputText object { annotations, text, type, logprobs }` + - `parameters: map[unknown]` - A text output from the model. + A JSON schema object describing the parameters of the function. - - `BetaResponseOutputRefusal object { refusal, type }` + - `strict: boolean` - A refusal from the model. + Whether strict parameter validation is enforced for this function tool. - - `ReasoningText object { text, type }` + - `type: "function"` - Reasoning text from the model. + The type of the function tool. Always `function`. - - `text: string` + - `"function"` - The reasoning text from the model. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `type: "reasoning_text"` + The tool invocation context(s). - The type of the reasoning text. Always `reasoning_text`. + - `"direct"` - - `"reasoning_text"` + - `"programmatic"` - - `sequence_number: number` + - `defer_loading: optional boolean` - The sequence number of this event. + Whether this function is deferred and loaded via tool search. - - `type: "response.content_part.added"` + - `description: optional string` - The type of the event. Always `response.content_part.added`. + A description of the function. Used by the model to determine whether or not to call the function. - - `"response.content_part.added"` + - `output_schema: optional map[unknown]` - - `agent: optional object { agent_name }` + A JSON schema object describing the JSON value encoded in string outputs for this function. - The agent that owns this multi-agent streaming event. + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - - `agent_name: 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 canonical name of the agent that produced this item. + - `type: "file_search"` - - `BetaResponseContentPartDoneEvent object { content_index, item_id, output_index, 4 more }` + The type of the file search tool. Always `file_search`. - Emitted when a content part is done. + - `"file_search"` - - `content_index: number` + - `vector_store_ids: array of string` - The index of the content part that is done. + The IDs of the vector stores to search. - - `item_id: string` + - `filters: optional object { key, type, value } or object { filters, type }` - The ID of the output item that the content part was added to. + A filter to apply. - - `output_index: number` + - `ComparisonFilter object { key, type, value }` - The index of the output item that the content part was added to. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `part: BetaResponseOutputText or BetaResponseOutputRefusal or object { text, type }` + - `key: string` - The content part that is done. + The key to compare against the value. - - `BetaResponseOutputText object { annotations, text, type, logprobs }` + - `type: "eq" or "ne" or "gt" or 5 more` - A text output from the model. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `BetaResponseOutputRefusal object { refusal, 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 refusal from the model. + - `"eq"` - - `ReasoningText object { text, type }` + - `"ne"` - Reasoning text from the model. + - `"gt"` - - `text: string` + - `"gte"` - The reasoning text from the model. + - `"lt"` - - `type: "reasoning_text"` + - `"lte"` - The type of the reasoning text. Always `reasoning_text`. + - `"in"` - - `"reasoning_text"` + - `"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. - - `type: "response.content_part.done"` + - `string` - The type of the event. Always `response.content_part.done`. + - `number` - - `"response.content_part.done"` + - `boolean` - - `agent: optional object { agent_name }` + - `array of string or number` - The agent that owns this multi-agent streaming event. + - `string` - - `agent_name: string` + - `number` - The canonical name of the agent that produced this item. + - `CompoundFilter object { filters, type }` - - `BetaResponseCreatedEvent object { response, sequence_number, type, agent }` + Combine multiple filters using `and` or `or`. - An event that is emitted when a response is created. + - `filters: array of object { key, type, value } or unknown` - - `response: BetaResponse` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - The response that was created. + - `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 for this event. + - `key: string` - - `type: "response.created"` + The key to compare against the value. - The type of the event. Always `response.created`. + - `type: "eq" or "ne" or "gt" or 5 more` - - `"response.created"` + 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"` - - `BetaResponseErrorEvent object { code, message, param, 3 more }` + - `"gte"` - Emitted when an error occurs. + - `"lt"` - - `code: string` + - `"lte"` - The error code. + - `"in"` - - `message: string` + - `"nin"` - The error message. + - `value: string or number or boolean or array of string or number` - - `param: string` + The value to compare against the attribute key; supports string, number, or boolean types. - The error parameter. + - `string` - - `sequence_number: number` + - `number` - The sequence number of this event. + - `boolean` - - `type: "error"` + - `array of string or number` - The type of the event. Always `error`. + - `string` - - `"error"` + - `number` - - `agent: optional object { agent_name }` + - `unknown` - The agent that owns this multi-agent streaming event. + - `type: "and" or "or"` - - `agent_name: string` + Type of operation: `and` or `or`. - The canonical name of the agent that produced this item. + - `"and"` - - `BetaResponseFileSearchCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` + - `"or"` - Emitted when a file search call is completed (results found). + - `max_num_results: optional number` - - `item_id: string` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - The ID of the output item that the file search call is initiated. + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `output_index: number` + Ranking options for search. - The index of the output item that the file search call is initiated. + - `hybrid_search: optional object { embedding_weight, text_weight }` - - `sequence_number: number` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - The sequence number of this event. + - `embedding_weight: number` - - `type: "response.file_search_call.completed"` + The weight of the embedding in the reciprocal ranking fusion. - The type of the event. Always `response.file_search_call.completed`. + - `text_weight: number` - - `"response.file_search_call.completed"` + The weight of the text in the reciprocal ranking fusion. - - `agent: optional object { agent_name }` + - `ranker: optional "auto" or "default-2024-11-15"` - The agent that owns this multi-agent streaming event. + The ranker to use for the file search. - - `agent_name: string` + - `"auto"` - The canonical name of the agent that produced this item. + - `"default-2024-11-15"` - - `BetaResponseFileSearchCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` + - `score_threshold: optional number` - Emitted when a file search call is initiated. + 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. - - `item_id: string` + - `Computer object { type }` - The ID of the output item that the file search call is initiated. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `output_index: number` + - `type: "computer"` - The index of the output item that the file search call is initiated. + The type of the computer tool. Always `computer`. - - `sequence_number: number` + - `"computer"` - The sequence number of this event. + - `ComputerUsePreview object { display_height, display_width, environment, type }` - - `type: "response.file_search_call.in_progress"` + 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 event. Always `response.file_search_call.in_progress`. + - `display_height: number` - - `"response.file_search_call.in_progress"` + The height of the computer display. - - `agent: optional object { agent_name }` + - `display_width: number` - The agent that owns this multi-agent streaming event. + 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. - - `BetaResponseFileSearchCallSearchingEvent object { item_id, output_index, sequence_number, 2 more }` + - `"windows"` - Emitted when a file search is currently searching. + - `"mac"` - - `item_id: string` + - `"linux"` - The ID of the output item that the file search call is initiated. + - `"ubuntu"` - - `output_index: number` + - `"browser"` - The index of the output item that the file search call is searching. + - `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.file_search_call.searching"` + - `WebSearch object { type, filters, search_context_size, user_location }` - The type of the event. Always `response.file_search_call.searching`. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - - `"response.file_search_call.searching"` + - `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 }` - - `BetaResponseFunctionCallArgumentsDeltaEvent object { delta, item_id, output_index, 3 more }` + Filters for the search. - Emitted when there is a partial function-call arguments delta. + - `allowed_domains: optional array of string` - - `delta: string` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - The function-call arguments delta that is 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 function-call arguments delta is 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 function-call arguments delta is added to. + - `"medium"` - - `sequence_number: number` + - `"high"` - The sequence number of this event. + - `user_location: optional object { city, country, region, 2 more }` - - `type: "response.function_call_arguments.delta"` + The approximate location of the user. - The type of the event. Always `response.function_call_arguments.delta`. + - `city: optional string` - - `"response.function_call_arguments.delta"` + Free text input for the city of the user, e.g. `San Francisco`. - - `agent: optional object { agent_name }` + - `country: optional string` - The agent that owns this multi-agent streaming event. + 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`. - - `BetaResponseFunctionCallArgumentsDoneEvent object { arguments, item_id, name, 4 more }` + - `timezone: optional string` - Emitted when function-call arguments are finalized. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `arguments: string` + - `type: optional "approximate"` - The function-call arguments. + The type of location approximation. Always `approximate`. - - `item_id: string` + - `"approximate"` - The ID of the item. + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `name: 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 name of the function that was called. + - `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. + - `type: "mcp"` - - `sequence_number: number` + The type of the MCP tool. Always `mcp`. - The sequence number of this event. + - `"mcp"` - - `type: "response.function_call_arguments.done"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"response.function_call_arguments.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` + - `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. - - `BetaResponseInProgressEvent object { response, sequence_number, type, agent }` + - `McpAllowedTools = array of string` - Emitted when the response is in progress. + A string array of allowed tool names - - `response: BetaResponse` + - `McpToolFilter object { read_only, tool_names }` - The response that 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. + 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.in_progress"` + - `tool_names: optional array of string` - The type of the event. Always `response.in_progress`. + List of allowed tool names. - - `"response.in_progress"` + - `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 owns this multi-agent streaming event. + - `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: - - `BetaResponseFailedEvent object { response, sequence_number, type, agent }` + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - An event that is emitted when a response fails. + - `"connector_dropbox"` - - `response: BetaResponse` + - `"connector_gmail"` - The response that failed. + - `"connector_googlecalendar"` - - `sequence_number: number` + - `"connector_googledrive"` - The sequence number of this event. + - `"connector_microsoftteams"` - - `type: "response.failed"` + - `"connector_outlookcalendar"` - The type of the event. Always `response.failed`. + - `"connector_outlookemail"` - - `"response.failed"` + - `"connector_sharepoint"` - - `agent: optional object { agent_name }` + - `defer_loading: optional boolean` - The agent that owns this multi-agent streaming event. + 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. - - `BetaResponseIncompleteEvent object { response, sequence_number, type, agent }` + - `require_approval: optional object { always, never } or "always" or "never"` - An event that is emitted when a response finishes as incomplete. + Specify which of the MCP server's tools require approval. - - `response: BetaResponse` + - `McpToolApprovalFilter object { always, never }` - The response that was 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. - - `sequence_number: number` + - `always: optional object { read_only, tool_names }` - The sequence number of this event. + A filter object to specify which tools are allowed. - - `type: "response.incomplete"` + - `read_only: optional boolean` - The type of the event. Always `response.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. - - `"response.incomplete"` + - `tool_names: optional array of string` - - `agent: optional object { agent_name }` + List of allowed tool names. - The agent that owns this multi-agent streaming event. + - `never: 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` - - `BetaResponseOutputItemAddedEvent object { item, output_index, sequence_number, 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. - Emitted when a new output item is added. + - `tool_names: optional array of string` - - `item: BetaResponseOutputItem` + List of allowed tool names. - The output item that was added. + - `McpToolApprovalSetting = "always" or "never"` - - `BetaResponseOutputMessage object { id, content, role, 4 more }` + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - An output message from the model. + - `"always"` - - `FileSearchCall object { id, queries, status, 3 more }` + - `"never"` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `server_description: optional string` - - `FunctionCall object { arguments, call_id, name, 6 more }` + Optional description of the MCP server, used to provide more context. - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `server_url: optional string` - - `FunctionCallOutput object { id, call_id, output, 5 more }` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `AgentMessage object { id, author, content, 3 more }` + - `tunnel_id: optional string` - - `MultiAgentCall object { id, action, arguments, 3 more }` + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `MultiAgentCallOutput object { id, action, call_id, 3 more }` + - `CodeInterpreter object { container, type, allowed_callers }` - - `WebSearchCall object { id, action, status, 2 more }` + A tool that runs Python code to help generate a response to a prompt. - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `ComputerCall object { id, call_id, pending_safety_checks, 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. - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + - `string` - - `ComputerCallOutput object { id, call_id, output, 5 more }` + The container ID. - - `Reasoning object { id, summary, type, 4 more }` + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - 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](https://platform.openai.com/docs/guides/conversation-state). + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `Program object { id, call_id, code, 3 more }` + - `type: "auto"` - - `ProgramOutput object { id, call_id, result, 3 more }` + Always `auto`. - - `ToolSearchCall object { id, arguments, call_id, 5 more }` + - `"auto"` - - `ToolSearchOutput object { id, call_id, execution, 5 more }` + - `file_ids: optional array of string` - - `AdditionalTools object { id, role, tools, 2 more }` + An optional list of uploaded files to make available to your code. - - `Compaction object { id, encrypted_content, type, 2 more }` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + The memory limit for the code interpreter container. - - `ImageGenerationCall object { id, result, status, 2 more }` + - `"1g"` - An image generation request made by the model. + - `"4g"` - - `CodeInterpreterCall object { id, code, container_id, 4 more }` + - `"16g"` - A tool call to run code. + - `"64g"` - - `LocalShellCall object { id, action, call_id, 3 more }` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - A tool call to run a command on the local shell. + Network access policy for the container. - - `LocalShellCallOutput object { id, output, type, 2 more }` + - `BetaContainerNetworkPolicyDisabled object { type }` - The output of a local shell tool call. + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `ShellCall object { id, action, call_id, 6 more }` + - `type: "code_interpreter"` - A tool call that executes one or more shell commands in a managed environment. + The type of the code interpreter tool. Always `code_interpreter`. - - `ShellCallOutput object { id, call_id, max_output_length, 6 more }` + - `"code_interpreter"` - The output of a shell tool call that was emitted. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `ApplyPatchCall object { id, call_id, operation, 5 more }` + The tool invocation context(s). - A tool call that applies file diffs by creating, deleting, or updating files. + - `"direct"` - - `ApplyPatchCallOutput object { id, call_id, status, 5 more }` + - `"programmatic"` - The output emitted by an apply patch tool call. + - `ProgrammaticToolCalling object { type }` - - `McpCall object { id, arguments, name, 7 more }` + - `type: "programmatic_tool_calling"` - An invocation of a tool on an MCP server. + The type of the tool. Always `programmatic_tool_calling`. - - `McpListTools object { id, server_label, tools, 3 more }` + - `"programmatic_tool_calling"` - A list of tools available on an MCP server. + - `ImageGeneration object { type, action, background, 9 more }` - - `McpApprovalRequest object { id, arguments, name, 3 more }` + A tool that generates images using the GPT image models. - A request for human approval of a tool invocation. + - `type: "image_generation"` - - `McpApprovalResponse object { id, approval_request_id, approve, 3 more }` + The type of the image generation tool. Always `image_generation`. - A response to an MCP approval request. + - `"image_generation"` - - `CustomToolCall object { call_id, input, name, 5 more }` + - `action: optional "generate" or "edit" or "auto"` - A call to a custom tool created by the model. + Whether to generate a new image or edit an existing image. Default: `auto`. - - `CustomToolCallOutput object { id, call_id, output, 5 more }` + - `"generate"` - - `output_index: number` + - `"edit"` - The index of the output item that was added. + - `"auto"` - - `sequence_number: number` + - `background: optional "transparent" or "opaque" or "auto"` - The sequence number of this event. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - - `type: "response.output_item.added"` + - `"transparent"` - The type of the event. Always `response.output_item.added`. + - `"opaque"` - - `"response.output_item.added"` + - `"auto"` - - `agent: optional object { agent_name }` + - `input_fidelity: optional "high" or "low"` - The agent that owns this multi-agent streaming event. + 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_name: string` + - `"high"` - The canonical name of the agent that produced this item. + - `"low"` - - `BetaResponseOutputItemDoneEvent object { item, output_index, sequence_number, 2 more }` + - `input_image_mask: optional object { file_id, image_url }` - Emitted when an output item is marked done. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `item: BetaResponseOutputItem` + - `file_id: optional string` - The output item that was marked done. + File ID for the mask image. - - `output_index: number` + - `image_url: optional string` - The index of the output item that was marked done. + Base64-encoded mask image. - - `sequence_number: number` + - `model: optional string or "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.output_item.done"` + - `string` - The type of the event. Always `response.output_item.done`. + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `"response.output_item.done"` + The image generation model to use. Default: `gpt-image-1`. - - `agent: optional object { agent_name }` + - `"gpt-image-1"` - The agent that owns this multi-agent streaming event. + - `"gpt-image-1-mini"` - - `agent_name: string` + - `"gpt-image-1.5"` - The canonical name of the agent that produced this item. + - `moderation: optional "auto" or "low"` - - `BetaResponseReasoningSummaryPartAddedEvent object { item_id, output_index, part, 4 more }` + Moderation level for the generated image. Default: `auto`. - Emitted when a new reasoning summary part is added. + - `"auto"` - - `item_id: string` + - `"low"` - The ID of the item this summary part is associated with. + - `output_compression: optional number` - - `output_index: number` + Compression level for the output image. Default: 100. - The index of the output item this summary part is associated with. + - `output_format: optional "png" or "webp" or "jpeg"` - - `part: object { text, type }` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - The summary part that was added. + - `"png"` - - `text: string` + - `"webp"` - The text of the summary part. + - `"jpeg"` - - `type: "summary_text"` + - `partial_images: optional number` - The type of the summary part. Always `summary_text`. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `"summary_text"` + - `quality: optional "low" or "medium" or "high" or "auto"` - - `sequence_number: number` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - The sequence number of this event. + - `"low"` - - `summary_index: number` + - `"medium"` - The index of the summary part within the reasoning summary. + - `"high"` - - `type: "response.reasoning_summary_part.added"` + - `"auto"` - The type of the event. Always `response.reasoning_summary_part.added`. + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `"response.reasoning_summary_part.added"` + 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"` - - `BetaResponseReasoningSummaryPartDoneEvent object { item_id, output_index, part, 5 more }` + - `"1024x1536"` - Emitted when a reasoning summary part is completed. + - `"1536x1024"` - - `item_id: string` + - `"auto"` - The ID of the item this summary part is associated with. + - `LocalShell object { type }` - - `output_index: number` + A tool that allows the model to execute shell commands in a local environment. - The index of the output item this summary part is associated with. + - `type: "local_shell"` - - `part: object { text, type }` + The type of the local shell tool. Always `local_shell`. - The completed summary part. + - `"local_shell"` - - `text: string` + - `Shell object { type, allowed_callers, environment }` - The text of the summary part. + A tool that allows the model to execute shell commands. - - `type: "summary_text"` + - `type: "shell"` - The type of the summary part. Always `summary_text`. + The type of the shell tool. Always `shell`. - - `"summary_text"` + - `"shell"` - - `sequence_number: number` + - `allowed_callers: optional array of "direct" or "programmatic"` - The sequence number of this event. + The tool invocation context(s). - - `summary_index: number` + - `"direct"` - The index of the summary part within the reasoning summary. + - `"programmatic"` - - `type: "response.reasoning_summary_part.done"` + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - The type of the event. Always `response.reasoning_summary_part.done`. + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - - `"response.reasoning_summary_part.done"` + - `BetaLocalEnvironment object { type, skills }` - - `agent: optional object { agent_name }` + - `BetaContainerReference object { container_id, type }` - The agent that owns this multi-agent streaming event. + - `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` - - `status: optional "incomplete"` + The name of the custom tool, used to identify it in tool calls. - The completion status of the summary part. Omitted when the part completed - normally and set to `incomplete` when generation was interrupted. + - `type: "custom"` - - `"incomplete"` + The type of the custom tool. Always `custom`. - - `BetaResponseReasoningSummaryTextDeltaEvent object { delta, item_id, output_index, 4 more }` + - `"custom"` - Emitted when a delta is added to a reasoning summary text. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `delta: string` + The tool invocation context(s). - The text delta that was added to the summary. + - `"direct"` - - `item_id: string` + - `"programmatic"` - The ID of the item this summary text delta is associated with. + - `defer_loading: optional boolean` - - `output_index: number` + Whether this tool should be deferred and discovered via tool search. - The index of the output item this summary text delta is associated with. + - `description: optional string` - - `sequence_number: number` + Optional description of the custom tool, used to provide more context. - The sequence number of this event. + - `format: optional object { type } or object { definition, syntax, type }` - - `summary_index: number` + The input format for the custom tool. Default is unconstrained text. - The index of the summary part within the reasoning summary. + - `Text object { type }` - - `type: "response.reasoning_summary_text.delta"` + Unconstrained free-form text. - The type of the event. Always `response.reasoning_summary_text.delta`. + - `type: "text"` - - `"response.reasoning_summary_text.delta"` + 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` - - `BetaResponseReasoningSummaryTextDoneEvent object { item_id, output_index, sequence_number, 4 more }` + The grammar definition. - Emitted when a reasoning summary text is completed. + - `syntax: "lark" or "regex"` - - `item_id: string` + The syntax of the grammar definition. One of `lark` or `regex`. - The ID of the item this summary text is associated with. + - `"lark"` - - `output_index: number` + - `"regex"` - The index of the output item this summary text is associated with. + - `type: "grammar"` - - `sequence_number: number` + Grammar format. Always `grammar`. - The sequence number of this event. + - `"grammar"` - - `summary_index: number` + - `Namespace object { description, name, tools, type }` - The index of the summary part within the reasoning summary. + Groups function/custom tools under a shared namespace. - - `text: string` + - `description: string` - The full text of the completed reasoning summary. + A description of the namespace shown to the model. - - `type: "response.reasoning_summary_text.done"` + - `name: string` - The type of the event. Always `response.reasoning_summary_text.done`. + The namespace name used in tool calls (for example, `crm`). - - `"response.reasoning_summary_text.done"` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - - `agent: optional object { agent_name }` + The function/custom tools available inside this namespace. - The agent that owns this multi-agent streaming event. + - `Function object { name, type, allowed_callers, 5 more }` - - `agent_name: string` + - `name: string` - The canonical name of the agent that produced this item. + - `type: "function"` - - `BetaResponseReasoningTextDeltaEvent object { content_index, delta, item_id, 4 more }` + - `"function"` - Emitted when a delta is added to a reasoning text. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `content_index: number` + The tool invocation context(s). - The index of the reasoning content part this delta is associated with. + - `"direct"` - - `delta: string` + - `"programmatic"` - The text delta that was added to the reasoning content. + - `defer_loading: optional boolean` - - `item_id: string` + Whether this function should be deferred and discovered via tool search. - The ID of the item this reasoning text delta is associated with. + - `description: optional string` - - `output_index: number` + - `output_schema: optional map[unknown]` - The index of the output item this reasoning text delta is associated with. + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `sequence_number: number` + - `parameters: optional unknown` - The sequence number of this event. + - `strict: optional boolean` - - `type: "response.reasoning_text.delta"` + 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 event. Always `response.reasoning_text.delta`. + - `Custom object { name, type, allowed_callers, 3 more }` - - `"response.reasoning_text.delta"` + 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 owns this multi-agent streaming event. + 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`. - - `BetaResponseReasoningTextDoneEvent object { content_index, item_id, output_index, 4 more }` + - `"custom"` - Emitted when a reasoning text is completed. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `content_index: number` + The tool invocation context(s). - The index of the reasoning content part. + - `"direct"` - - `item_id: string` + - `"programmatic"` - The ID of the item this reasoning text is associated with. + - `defer_loading: optional boolean` - - `output_index: number` + Whether this tool should be deferred and discovered via tool search. - The index of the output item this reasoning text is associated with. + - `description: optional string` - - `sequence_number: number` + Optional description of the custom tool, used to provide more context. - The sequence number of this event. + - `format: optional object { type } or object { definition, syntax, type }` - - `text: string` + The input format for the custom tool. Default is unconstrained text. - The full text of the completed reasoning content. + - `Text object { type }` - - `type: "response.reasoning_text.done"` + Unconstrained free-form text. - The type of the event. Always `response.reasoning_text.done`. + - `type: "text"` - - `"response.reasoning_text.done"` + 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` - - `BetaResponseRefusalDeltaEvent object { content_index, delta, item_id, 4 more }` + The grammar definition. - Emitted when there is a partial refusal text. + - `syntax: "lark" or "regex"` - - `content_index: number` + The syntax of the grammar definition. One of `lark` or `regex`. - The index of the content part that the refusal text is added to. + - `"lark"` - - `delta: string` + - `"regex"` - The refusal text that is added. + - `type: "grammar"` - - `item_id: string` + Grammar format. Always `grammar`. - The ID of the output item that the refusal text is added to. + - `"grammar"` - - `output_index: number` + - `type: "namespace"` - The index of the output item that the refusal text is added to. + The type of the tool. Always `namespace`. - - `sequence_number: number` + - `"namespace"` - The sequence number of this event. + - `ToolSearch object { type, description, execution, parameters }` - - `type: "response.refusal.delta"` + Hosted or BYOT tool search configuration for deferred tools. - The type of the event. Always `response.refusal.delta`. + - `type: "tool_search"` - - `"response.refusal.delta"` + The type of the tool. Always `tool_search`. - - `agent: optional object { agent_name }` + - `"tool_search"` - The agent that owns this multi-agent streaming event. + - `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"` - - `BetaResponseRefusalDoneEvent object { content_index, item_id, output_index, 4 more }` + Whether tool search is executed by the server or by the client. - Emitted when refusal text is finalized. + - `"server"` - - `content_index: number` + - `"client"` - The index of the content part that the refusal text is finalized. + - `parameters: optional unknown` - - `item_id: string` + Parameter schema for a client-executed tool search tool. - The ID of the output item that the refusal text is finalized. + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - - `output_index: 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 index of the output item that the refusal text is finalized. + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `refusal: string` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - The refusal text that is finalized. + - `"web_search_preview"` - - `sequence_number: number` + - `"web_search_preview_2025_03_11"` - The sequence number of this event. + - `search_content_types: optional array of "text" or "image"` - - `type: "response.refusal.done"` + - `"text"` - The type of the event. Always `response.refusal.done`. + - `"image"` - - `"response.refusal.done"` + - `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 owns this multi-agent streaming event. + - `"low"` - - `agent_name: string` + - `"medium"` - The canonical name of the agent that produced this item. + - `"high"` - - `BetaResponseTextDeltaEvent object { content_index, delta, item_id, 5 more }` + - `user_location: optional object { type, city, country, 2 more }` - Emitted when there is an additional text delta. + The user's location. - - `content_index: number` + - `type: "approximate"` - The index of the content part that the text delta was added to. + The type of location approximation. Always `approximate`. - - `delta: string` + - `"approximate"` - The text delta that was added. + - `city: optional string` - - `item_id: string` + Free text input for the city of the user, e.g. `San Francisco`. - The ID of the output item that the text delta was added to. + - `country: optional string` - - `logprobs: array of object { token, logprob, top_logprobs }` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The log probabilities of the tokens in the delta. + - `region: optional string` - - `token: string` + Free text input for the region of the user, e.g. `California`. - A possible text token. + - `timezone: optional string` - - `logprob: number` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The log probability of this token. + - `ApplyPatch object { type, allowed_callers }` - - `top_logprobs: optional array of object { token, logprob }` + Allows the assistant to create, delete, or update files using unified diffs. - The log probabilities of up to 20 of the most likely tokens. + - `type: "apply_patch"` - - `token: optional string` + The type of the tool. Always `apply_patch`. - A possible text token. + - `"apply_patch"` - - `logprob: optional number` + - `allowed_callers: optional array of "direct" or "programmatic"` - The log probability of this token. + The tool invocation context(s). - - `output_index: number` + - `"direct"` - The index of the output item that the text delta was added to. + - `"programmatic"` - - `sequence_number: number` + - `type: "additional_tools"` - The sequence number for this event. + The item type. Always `additional_tools`. - - `type: "response.output_text.delta"` + - `"additional_tools"` - The type of the event. Always `response.output_text.delta`. + - `id: optional string` - - `"response.output_text.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. - - `BetaResponseTextDoneEvent object { content_index, item_id, logprobs, 5 more }` - - Emitted when text content is finalized. - - - `content_index: number` + - `Reasoning object { id, summary, type, 4 more }` - The index of the content part that the text content is finalized. + 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). - - `item_id: string` + - `id: string` - The ID of the output item that the text content is finalized. + The unique identifier of the reasoning content. - - `logprobs: array of object { token, logprob, top_logprobs }` + - `summary: array of object { text, type }` - The log probabilities of the tokens in the delta. + Reasoning summary content. - - `token: string` + - `text: string` - A possible text token. + A summary of the reasoning output from the model so far. - - `logprob: number` + - `type: "summary_text"` - The log probability of this token. + The type of the object. Always `summary_text`. - - `top_logprobs: optional array of object { token, logprob }` + - `"summary_text"` - The log probabilities of up to 20 of the most likely tokens. + - `type: "reasoning"` - - `token: optional string` + The type of the object. Always `reasoning`. - A possible text token. + - `"reasoning"` - - `logprob: optional number` + - `agent: optional object { agent_name }` - The log probability of this token. + The agent that produced this item. - - `output_index: number` + - `agent_name: string` - The index of the output item that the text content is finalized. + The canonical name of the agent that produced this item. - - `sequence_number: number` + - `content: optional array of object { text, type }` - The sequence number for this event. + Reasoning text content. - `text: string` - The text content that is finalized. + The reasoning text from the model. - - `type: "response.output_text.done"` + - `type: "reasoning_text"` - The type of the event. Always `response.output_text.done`. + The type of the reasoning text. Always `reasoning_text`. - - `"response.output_text.done"` + - `"reasoning_text"` - - `agent: optional object { agent_name }` + - `encrypted_content: optional string` - The agent that owns this multi-agent streaming event. + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - - `agent_name: string` + - `status: optional "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. - - `BetaResponseWebSearchCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` + - `"in_progress"` - Emitted when a web search call is completed. + - `"completed"` - - `item_id: string` + - `"incomplete"` - Unique ID for the output item associated with the web search call. + - `Compaction object { encrypted_content, type, id, agent }` - - `output_index: number` + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). - The index of the output item that the web search call is associated with. + - `encrypted_content: string` - - `sequence_number: number` + The encrypted content of the compaction summary. - The sequence number of the web search call being processed. + - `type: "compaction"` - - `type: "response.web_search_call.completed"` + The type of the item. Always `compaction`. - The type of the event. Always `response.web_search_call.completed`. + - `"compaction"` - - `"response.web_search_call.completed"` + - `id: optional string` + + 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. - - `BetaResponseWebSearchCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` - - Emitted when a web search call is initiated. - - - `item_id: string` - - Unique ID for the output item associated with the web search call. + - `ImageGenerationCall object { id, result, status, 2 more }` - - `output_index: number` + An image generation request made by the model. - The index of the output item that the web search call is associated with. + - `id: string` - - `sequence_number: number` + The unique ID of the image generation call. - The sequence number of the web search call being processed. + - `result: string` - - `type: "response.web_search_call.in_progress"` + The generated image encoded in base64. - The type of the event. Always `response.web_search_call.in_progress`. + - `status: "in_progress" or "completed" or "generating" or "failed"` - - `"response.web_search_call.in_progress"` + The status of the image generation call. - - `agent: optional object { agent_name }` + - `"in_progress"` - The agent that owns this multi-agent streaming event. + - `"completed"` - - `agent_name: string` + - `"generating"` - The canonical name of the agent that produced this item. + - `"failed"` - - `BetaResponseWebSearchCallSearchingEvent object { item_id, output_index, sequence_number, 2 more }` + - `type: "image_generation_call"` - Emitted when a web search call is executing. + The type of the image generation call. Always `image_generation_call`. - - `item_id: string` + - `"image_generation_call"` - Unique ID for the output item associated with the web search call. + - `agent: optional object { agent_name }` - - `output_index: number` + The agent that produced this item. - The index of the output item that the web search call is associated with. + - `agent_name: string` - - `sequence_number: number` + The canonical name of the agent that produced this item. - The sequence number of the web search call being processed. + - `CodeInterpreterCall object { id, code, container_id, 4 more }` - - `type: "response.web_search_call.searching"` + A tool call to run code. - The type of the event. Always `response.web_search_call.searching`. + - `id: string` - - `"response.web_search_call.searching"` + The unique ID of the code interpreter tool call. - - `agent: optional object { agent_name }` + - `code: string` - The agent that owns this multi-agent streaming event. + The code to run, or null if not available. - - `agent_name: string` + - `container_id: string` - The canonical name of the agent that produced this item. + The ID of the container used to run the code. - - `BetaResponseImageGenCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` + - `outputs: array of object { logs, type } or object { type, url }` - Emitted when an image generation tool call has completed and the final image is available. + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `item_id: string` + - `Logs object { logs, type }` - The unique identifier of the image generation item being processed. + The logs output from the code interpreter. - - `output_index: number` + - `logs: string` - The index of the output item in the response's output array. + The logs output from the code interpreter. - - `sequence_number: number` + - `type: "logs"` - The sequence number of this event. + The type of the output. Always `logs`. - - `type: "response.image_generation_call.completed"` + - `"logs"` - The type of the event. Always 'response.image_generation_call.completed'. + - `Image object { type, url }` - - `"response.image_generation_call.completed"` + 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` - - `BetaResponseImageGenCallGeneratingEvent object { item_id, output_index, sequence_number, 2 more }` + The URL of the image output from the code interpreter. - Emitted when an image generation tool call is actively generating an image (intermediate state). + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - - `item_id: string` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - The unique identifier of the image generation item being processed. + - `"in_progress"` - - `output_index: number` + - `"completed"` - The index of the output item in the response's output array. + - `"incomplete"` - - `sequence_number: number` + - `"interpreting"` - The sequence number of the image generation item being processed. + - `"failed"` - - `type: "response.image_generation_call.generating"` + - `type: "code_interpreter_call"` - The type of the event. Always 'response.image_generation_call.generating'. + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `"response.image_generation_call.generating"` + - `"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. - - `BetaResponseImageGenCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` - - Emitted when an image generation tool call is in progress. + - `LocalShellCall object { id, action, call_id, 3 more }` - - `item_id: string` + A tool call to run a command on the local shell. - The unique identifier of the image generation item being processed. + - `id: string` - - `output_index: number` + The unique ID of the local shell call. - The index of the output item in the response's output array. + - `action: object { command, env, type, 3 more }` - - `sequence_number: number` + Execute a shell command on the server. - The sequence number of the image generation item being processed. + - `command: array of string` - - `type: "response.image_generation_call.in_progress"` + The command to run. - The type of the event. Always 'response.image_generation_call.in_progress'. + - `env: map[string]` - - `"response.image_generation_call.in_progress"` + Environment variables to set for the command. - - `agent: optional object { agent_name }` + - `type: "exec"` - The agent that owns this multi-agent streaming event. + The type of the local shell action. Always `exec`. - - `agent_name: string` + - `"exec"` - The canonical name of the agent that produced this item. + - `timeout_ms: optional number` - - `BetaResponseImageGenCallPartialImageEvent object { item_id, output_index, partial_image_b64, 4 more }` + Optional timeout in milliseconds for the command. - Emitted when a partial image is available during image generation streaming. + - `user: optional string` - - `item_id: string` + Optional user to run the command as. - The unique identifier of the image generation item being processed. + - `working_directory: optional string` - - `output_index: number` + Optional working directory to run the command in. - The index of the output item in the response's output array. + - `call_id: string` - - `partial_image_b64: string` + The unique ID of the local shell tool call generated by the model. - Base64-encoded partial image data, suitable for rendering as an image. + - `status: "in_progress" or "completed" or "incomplete"` - - `partial_image_index: number` + The status of the local shell call. - 0-based index for the partial image (backend is 1-based, but this is 0-based for the user). + - `"in_progress"` - - `sequence_number: number` + - `"completed"` - The sequence number of the image generation item being processed. + - `"incomplete"` - - `type: "response.image_generation_call.partial_image"` + - `type: "local_shell_call"` - The type of the event. Always 'response.image_generation_call.partial_image'. + The type of the local shell call. Always `local_shell_call`. - - `"response.image_generation_call.partial_image"` + - `"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. - - `BetaResponseMcpCallArgumentsDeltaEvent object { delta, item_id, output_index, 3 more }` - - Emitted when there is a delta (partial update) to the arguments of an MCP tool call. - - - `delta: string` - - A JSON string containing the partial update to the arguments for the MCP tool call. - - - `item_id: string` + - `LocalShellCallOutput object { id, output, type, 2 more }` - The unique identifier of the MCP tool call item being processed. + The output of a local shell tool call. - - `output_index: number` + - `id: string` - The index of the output item in the response's output array. + 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.mcp_call_arguments.delta"` + - `type: "local_shell_call_output"` - The type of the event. Always 'response.mcp_call_arguments.delta'. + The type of the local shell tool call output. Always `local_shell_call_output`. - - `"response.mcp_call_arguments.delta"` + - `"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. - - `BetaResponseMcpCallArgumentsDoneEvent object { arguments, item_id, output_index, 3 more }` + - `status: optional "in_progress" or "completed" or "incomplete"` - Emitted when the arguments for an MCP tool call are finalized. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `arguments: string` + - `"in_progress"` - A JSON string containing the finalized arguments for the MCP tool call. + - `"completed"` - - `item_id: string` + - `"incomplete"` - The unique identifier of the MCP tool call item being processed. + - `ShellCall object { action, call_id, type, 5 more }` - - `output_index: number` + A tool representing a request to execute one or more shell commands. - The index of the output item in the response's output array. + - `action: object { commands, max_output_length, timeout_ms }` - - `sequence_number: number` + The shell commands and limits that describe how to run the tool call. - The sequence number of this event. + - `commands: array of string` - - `type: "response.mcp_call_arguments.done"` + Ordered shell commands for the execution environment to run. - The type of the event. Always 'response.mcp_call_arguments.done'. + - `max_output_length: optional number` - - `"response.mcp_call_arguments.done"` + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - - `agent: optional object { agent_name }` + - `timeout_ms: optional number` - The agent that owns this multi-agent streaming event. + Maximum wall-clock time in milliseconds to allow the shell commands to run. - - `agent_name: string` + - `call_id: string` - The canonical name of the agent that produced this item. + The unique ID of the shell tool call generated by the model. - - `BetaResponseMcpCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` + - `type: "shell_call"` - Emitted when an MCP tool call has completed successfully. + The type of the item. Always `shell_call`. - - `item_id: string` + - `"shell_call"` - The ID of the MCP tool call item that completed. + - `id: optional string` - - `output_index: number` + The unique ID of the shell tool call. Populated when this item is returned via API. - The index of the output item that completed. + - `agent: optional object { agent_name }` - - `sequence_number: number` + The agent that produced this item. - The sequence number of this event. + - `agent_name: string` - - `type: "response.mcp_call.completed"` + The canonical name of the agent that produced this item. - The type of the event. Always 'response.mcp_call.completed'. + - `caller: optional object { type } or object { caller_id, type }` - - `"response.mcp_call.completed"` + The execution context that produced this tool call. - - `agent: optional object { agent_name }` + - `Direct object { type }` - The agent that owns this multi-agent streaming event. + - `type: "direct"` - - `agent_name: string` + The caller type. Always `direct`. - The canonical name of the agent that produced this item. + - `"direct"` - - `BetaResponseMcpCallFailedEvent object { item_id, output_index, sequence_number, 2 more }` + - `Program object { caller_id, type }` - Emitted when an MCP tool call has failed. + - `caller_id: string` - - `item_id: string` + The call ID of the program item that produced this tool call. - The ID of the MCP tool call item that failed. + - `type: "program"` - - `output_index: number` + The caller type. Always `program`. - The index of the output item that failed. + - `"program"` - - `sequence_number: number` + - `environment: optional BetaLocalEnvironment or BetaContainerReference` - The sequence number of this event. + The environment to execute the shell commands in. - - `type: "response.mcp_call.failed"` + - `BetaLocalEnvironment object { type, skills }` - The type of the event. Always 'response.mcp_call.failed'. + - `BetaContainerReference object { container_id, type }` - - `"response.mcp_call.failed"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `agent: optional object { agent_name }` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - 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"` - - `BetaResponseMcpCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` + - `ShellCallOutput object { call_id, output, type, 5 more }` - Emitted when an MCP tool call is in progress. + The streamed output items emitted by a shell tool call. - - `item_id: string` + - `call_id: string` - The unique identifier of the MCP tool call item being processed. + The unique ID of the shell tool call generated by the model. - - `output_index: number` + - `output: array of BetaResponseFunctionShellCallOutputContent` - The index of the output item in the response's output array. + Captured chunks of stdout and stderr output, along with their associated outcomes. - - `sequence_number: number` + - `outcome: object { type } or object { exit_code, type }` - The sequence number of this event. + The exit or timeout outcome associated with this shell call. - - `type: "response.mcp_call.in_progress"` + - `Timeout object { type }` - The type of the event. Always 'response.mcp_call.in_progress'. + Indicates that the shell call exceeded its configured time limit. - - `"response.mcp_call.in_progress"` + - `type: "timeout"` - - `agent: optional object { agent_name }` + The outcome type. Always `timeout`. - The agent that owns this multi-agent streaming event. + - `"timeout"` - - `agent_name: string` + - `Exit object { exit_code, type }` - The canonical name of the agent that produced this item. + Indicates that the shell commands finished and returned an exit code. - - `BetaResponseMcpListToolsCompletedEvent object { item_id, output_index, sequence_number, 2 more }` + - `exit_code: number` - Emitted when the list of available MCP tools has been successfully retrieved. + The exit code returned by the shell process. - - `item_id: string` + - `type: "exit"` - The ID of the MCP tool call item that produced this output. + The outcome type. Always `exit`. - - `output_index: number` + - `"exit"` - The index of the output item that was processed. + - `stderr: string` - - `sequence_number: number` + Captured stderr output for the shell call. - The sequence number of this event. + - `stdout: string` - - `type: "response.mcp_list_tools.completed"` + Captured stdout output for the shell call. - The type of the event. Always 'response.mcp_list_tools.completed'. + - `type: "shell_call_output"` - - `"response.mcp_list_tools.completed"` + 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 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. - - `BetaResponseMcpListToolsFailedEvent object { item_id, output_index, sequence_number, 2 more }` - - Emitted when the attempt to list available MCP tools has failed. + - `caller: optional object { type } or object { caller_id, type }` - - `item_id: string` + The execution context that produced this tool call. - The ID of the MCP tool call item that failed. + - `Direct object { type }` - - `output_index: number` + - `type: "direct"` - The index of the output item that failed. + The caller type. Always `direct`. - - `sequence_number: number` + - `"direct"` - The sequence number of this event. + - `Program object { caller_id, type }` - - `type: "response.mcp_list_tools.failed"` + - `caller_id: string` - The type of the event. Always 'response.mcp_list_tools.failed'. + The call ID of the program item that produced this tool call. - - `"response.mcp_list_tools.failed"` + - `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` + - `max_output_length: optional number` - The canonical name of the agent that produced this item. + The maximum number of UTF-8 characters captured for this shell call's combined output. - - `BetaResponseMcpListToolsInProgressEvent object { item_id, output_index, sequence_number, 2 more }` + - `status: optional "in_progress" or "completed" or "incomplete"` - Emitted when the system is in the process of retrieving the list of available MCP tools. + The status of the shell call output. - - `item_id: string` + - `"in_progress"` - The ID of the MCP tool call item that is being processed. + - `"completed"` - - `output_index: number` + - `"incomplete"` - The index of the output item that is being processed. + - `ApplyPatchCall object { call_id, operation, status, 4 more }` - - `sequence_number: number` + A tool call representing a request to create, delete, or update files using diff patches. - The sequence number of this event. + - `call_id: string` - - `type: "response.mcp_list_tools.in_progress"` + The unique ID of the apply patch tool call generated by the model. - The type of the event. Always 'response.mcp_list_tools.in_progress'. + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - - `"response.mcp_list_tools.in_progress"` + The specific create, delete, or update instruction for the apply_patch tool call. - - `agent: optional object { agent_name }` + - `CreateFile object { diff, path, type }` - The agent that owns this multi-agent streaming event. + Instruction for creating a new file via the apply_patch tool. - - `agent_name: string` + - `diff: string` - The canonical name of the agent that produced this item. + Unified diff content to apply when creating the file. - - `BetaResponseOutputTextAnnotationAddedEvent object { annotation, annotation_index, content_index, 5 more }` + - `path: string` - Emitted when an annotation is added to output text content. + Path of the file to create relative to the workspace root. - - `annotation: unknown` + - `type: "create_file"` - The annotation object being added. (See annotation schema for details.) + The operation type. Always `create_file`. - - `annotation_index: number` + - `"create_file"` - The index of the annotation within the content part. + - `DeleteFile object { path, type }` - - `content_index: number` + Instruction for deleting an existing file via the apply_patch tool. - The index of the content part within the output item. + - `path: string` - - `item_id: string` + Path of the file to delete relative to the workspace root. - The unique identifier of the item to which the annotation is being added. + - `type: "delete_file"` - - `output_index: number` + The operation type. Always `delete_file`. - The index of the output item in the response's output array. + - `"delete_file"` - - `sequence_number: number` + - `UpdateFile object { diff, path, type }` - The sequence number of this event. + Instruction for updating an existing file via the apply_patch tool. - - `type: "response.output_text.annotation.added"` + - `diff: string` - The type of the event. Always 'response.output_text.annotation.added'. + Unified diff content to apply to the existing file. - - `"response.output_text.annotation.added"` + - `path: string` - - `agent: optional object { agent_name }` + Path of the file to update relative to the workspace root. - The agent that owns this multi-agent streaming event. + - `type: "update_file"` - - `agent_name: string` + The operation type. Always `update_file`. - The canonical name of the agent that produced this item. + - `"update_file"` - - `BetaResponseQueuedEvent object { response, sequence_number, type, agent }` + - `status: "in_progress" or "completed"` - Emitted when a response is queued and waiting to be processed. + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `response: BetaResponse` + - `"in_progress"` - The full response object that is queued. + - `"completed"` - - `sequence_number: number` + - `type: "apply_patch_call"` - The sequence number for this event. + The type of the item. Always `apply_patch_call`. - - `type: "response.queued"` + - `"apply_patch_call"` - The type of the event. Always 'response.queued'. + - `id: optional string` - - `"response.queued"` + 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 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. - - `BetaResponseCustomToolCallInputDeltaEvent object { delta, item_id, output_index, 3 more }` - - Event representing a delta (partial update) to the input of a custom tool call. - - - `delta: string` - - The incremental input data (delta) for the custom tool call. - - - `item_id: string` - - Unique identifier for the API item associated with this event. + - `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 this delta applies to. + - `Direct object { type }` - - `sequence_number: number` + - `type: "direct"` - The sequence number of this event. + The caller type. Always `direct`. - - `type: "response.custom_tool_call_input.delta"` + - `"direct"` - The event type identifier. + - `Program object { caller_id, type }` - - `"response.custom_tool_call_input.delta"` + - `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"` - - `BetaResponseCustomToolCallInputDoneEvent object { input, item_id, output_index, 3 more }` + - `ApplyPatchCallOutput object { call_id, status, type, 4 more }` - Event indicating that input for a custom tool call is complete. + The streamed output emitted by an apply patch tool call. - - `input: string` + - `call_id: string` - The complete input data for the custom tool call. + The unique ID of the apply patch tool call generated by the model. - - `item_id: string` + - `status: "completed" or "failed"` - Unique identifier for the API item associated with this event. + The status of the apply patch tool call output. One of `completed` or `failed`. - - `output_index: number` + - `"completed"` - The index of the output this event applies to. + - `"failed"` - - `sequence_number: number` + - `type: "apply_patch_call_output"` - The sequence number of this event. + The type of the item. Always `apply_patch_call_output`. - - `type: "response.custom_tool_call_input.done"` + - `"apply_patch_call_output"` - The event type identifier. + - `id: optional string` - - `"response.custom_tool_call_input.done"` + 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. - - `ResponseInjectCreated object { response_id, sequence_number, type, stream_id }` - - Emitted when all injected input items were validated and committed to the - active response. + - `caller: optional object { type } or object { caller_id, type }` - - `response_id: string` + The execution context that produced this tool call. - The ID of the response that accepted the input. + - `Direct object { type }` - - `sequence_number: number` + - `type: "direct"` - The sequence number for this event. + The caller type. Always `direct`. - - `type: "response.inject.created"` + - `"direct"` - The event discriminator. Always `response.inject.created`. + - `Program object { caller_id, type }` - - `"response.inject.created"` + - `caller_id: string` - - `stream_id: optional string` + The call ID of the program item that produced this tool call. - The multiplexed WebSocket stream that emitted the event. This field is - present only when WebSocket multiplexing is enabled separately. + - `type: "program"` - - `ResponseInjectFailed object { error, input, response_id, 3 more }` + The caller type. Always `program`. - 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. + - `"program"` - - `error: object { code, message }` + - `output: optional string` - Information about why the input was not committed. + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - - `code: "response_already_completed" or "response_not_found"` + - `McpListTools object { id, server_label, tools, 3 more }` - A machine-readable error code. + A list of tools available on an MCP server. - - `"response_already_completed"` + - `id: string` - - `"response_not_found"` + The unique ID of the list. - - `message: string` + - `server_label: string` - A human-readable description of the error. + The label of the MCP server. - - `input: array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + - `tools: array of object { input_schema, name, annotations, description }` - The raw input items that were not committed. + The tools available on the server. - - `BetaEasyInputMessage object { content, role, phase, type }` + - `input_schema: unknown` - 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 JSON schema describing the tool's input. - - `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. - - `content: BetaResponseInputMessageContentList` + - `annotations: optional unknown` - A list of one or many input items to the model, containing different content - types. + Additional annotations about the tool. - - `role: "user" or "system" or "developer"` + - `description: optional string` - The role of the message input. One of `user`, `system`, or `developer`. + The description of the tool. - - `"user"` + - `type: "mcp_list_tools"` - - `"system"` + The type of the item. Always `mcp_list_tools`. - - `"developer"` + - `"mcp_list_tools"` - `agent: optional object { agent_name }` @@ -212339,60 +212803,35 @@ 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"` - - The type of the message input. Always set to `message`. - - - `"message"` - - - `BetaResponseOutputMessage object { id, content, role, 4 more }` + - `error: optional string` - An output message from the model. + Error message if the server could not list tools. - - `FileSearchCall object { id, queries, status, 3 more }` + - `McpApprovalRequest object { id, arguments, name, 3 more }` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + A request for human approval of a tool invocation. - `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 unique ID of the approval request. - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `arguments: string` - - `"in_progress"` + A JSON string of arguments for the tool. - - `"searching"` + - `name: string` - - `"completed"` + The name of the tool to run. - - `"incomplete"` + - `server_label: string` - - `"failed"` + The label of the MCP server making the request. - - `type: "file_search_call"` + - `type: "mcp_approval_request"` - The type of the file search tool call. Always `file_search_call`. + The type of the item. Always `mcp_approval_request`. - - `"file_search_call"` + - `"mcp_approval_request"` - `agent: optional object { agent_name }` @@ -212402,140 +212841,143 @@ 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 }` + - `McpApprovalResponse object { approval_request_id, approve, type, 3 more }` - The results of the file search tool call. + A response to an MCP approval request. - - `attributes: optional map[string or number or boolean]` + - `approval_request_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. Keys are strings - with a maximum length of 64 characters. Values are strings with a maximum - length of 512 characters, booleans, or numbers. + The ID of the approval request being answered. - - `string` + - `approve: boolean` - - `number` + Whether the request was approved. - - `boolean` + - `type: "mcp_approval_response"` - - `file_id: optional string` + The type of the item. Always `mcp_approval_response`. - The unique ID of the file. + - `"mcp_approval_response"` - - `filename: optional string` + - `id: optional string` - The name of the file. + The unique ID of the approval response - - `score: optional number` + - `agent: optional object { agent_name }` - The relevance score of the file - a value between 0 and 1. + The agent that produced this item. - - `text: optional string` + - `agent_name: string` - The text that was retrieved from the file. + The canonical name of the agent that produced this item. - - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` + - `reason: optional string` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + 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 computer call. + The unique ID of the tool call. - - `call_id: string` + - `arguments: string` - An identifier used when responding to the tool call with output. + A JSON string of the arguments passed to the tool. - - `pending_safety_checks: array of object { id, code, message }` + - `name: string` - The pending safety checks for the computer call. + The name of the tool that was run. - - `id: string` + - `server_label: string` - The ID of the pending safety check. + The label of the MCP server running the tool. - - `code: optional string` + - `type: "mcp_call"` - The type of the pending safety check. + The type of the item. Always `mcp_call`. - - `message: optional string` + - `"mcp_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. - 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"` + - `approval_request_id: optional string` - - `"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. - - `type: "computer_call"` + - `error: optional string` - The type of the computer call. Always `computer_call`. + The error from the tool call, if any. - - `"computer_call"` + - `output: optional string` - - `action: optional BetaComputerAction` + The output from the tool call. - A click action. + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - - `actions: optional BetaComputerActionList` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `"in_progress"` - - `agent: optional object { agent_name }` + - `"completed"` - The agent that produced this item. + - `"incomplete"` - - `agent_name: string` + - `"calling"` - The canonical name of the agent that produced this item. + - `"failed"` - - `ComputerCallOutput object { call_id, output, type, 4 more }` + - `CustomToolCallOutput object { call_id, output, type, 3 more }` - The output of a computer tool call. + The output of a custom tool call from your code, being sent back to the model. - `call_id: string` - The ID of the computer tool call that produced the output. + The call ID, used to map this custom tool call output to a custom tool call. - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - A computer screenshot image used with the computer use tool. + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `type: "computer_call_output"` + - `StringOutput = string` - The type of the computer tool call output. Always `computer_call_output`. + A string of the output of the custom tool call. - - `"computer_call_output"` + - `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 computer tool call output. + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `acknowledged_safety_checks: optional array of object { id, code, message }` + A text input to the model. - The safety checks reported by the API that have been acknowledged by the developer. + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `id: string` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - The ID of the pending safety check. + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `code: optional string` + A file input to the model. - The type of the pending safety check. + - `type: "custom_tool_call_output"` - - `message: optional string` + The type of the custom tool call output. Always `custom_tool_call_output`. - Details about the pending safety check. + - `"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 }` @@ -212545,111 +212987,113 @@ 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 the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input 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`. - - `WebSearchCall object { id, action, status, 2 more }` + - `"direct"` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `Program object { caller_id, type }` - - `id: string` + - `caller_id: string` - The unique ID of the web search tool call. + The call ID of the program item that produced this tool call. - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + - `type: "program"` - 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 caller type. Always `program`. - - `Search object { type, queries, query, sources }` + - `"program"` - Action type "search" - Performs a web search query. + - `CustomToolCall object { call_id, input, name, 5 more }` - - `type: "search"` + A call to a custom tool created by the model. - The action type. + - `call_id: string` - - `"search"` + An identifier used to map this custom tool call to a tool call output. - - `queries: optional array of string` + - `input: string` - The search queries. + The input for the custom tool call generated by the model. - - `query: optional string` + - `name: string` - The search query. + The name of the custom tool being called. - - `sources: optional array of object { type, url }` + - `type: "custom_tool_call"` - The sources used in the search. + The type of the custom tool call. Always `custom_tool_call`. - - `type: "url"` + - `"custom_tool_call"` - The type of source. Always `url`. + - `id: optional string` - - `"url"` + The unique ID of the custom tool call in the OpenAI platform. - - `url: string` + - `agent: optional object { agent_name }` - The URL of the source. + The agent that produced this item. - - `OpenPage object { type, url }` + - `agent_name: string` - Action type "open_page" - Opens a specific URL from search results. + The canonical name of the agent that produced this item. - - `type: "open_page"` + - `caller: optional object { type } or object { caller_id, type }` - The action type. + The execution context that produced this tool call. - - `"open_page"` + - `Direct object { type }` - - `url: optional string` + - `type: "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"` + - `"program"` - The action type. + - `namespace: optional string` - - `"find_in_page"` + The namespace of the custom tool being called. - - `url: string` + - `CompactionTrigger object { type, agent }` - The URL of the page searched for the pattern. + Compacts the current context. Must be the final input item. - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `type: "compaction_trigger"` - The status of the web search tool call. + The type of the item. Always `compaction_trigger`. - - `"in_progress"` + - `"compaction_trigger"` - - `"searching"` + - `agent: optional object { agent_name }` - - `"completed"` + The agent that produced this item. - - `"failed"` + - `agent_name: string` - - `type: "web_search_call"` + The canonical name of the agent that produced this item. - The type of the web search tool call. Always `web_search_call`. + - `ItemReference object { id, agent, type }` - - `"web_search_call"` + An internal identifier for an item to reference. + + - `id: string` + + The ID of the item to reference. - `agent: optional object { agent_name }` @@ -212659,32 +213103,35 @@ 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 }` + - `type: optional "item_reference"` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + The type of item to reference. Always `item_reference`. - - `arguments: string` + - `"item_reference"` - A JSON string of the arguments to pass to the function. + - `Program object { id, call_id, code, 3 more }` + + - `id: string` + + The unique ID of this program item. - `call_id: string` - The unique ID of the function tool call generated by the model. + The stable call ID of the program item. - - `name: string` + - `code: string` - The name of the function to run. + The JavaScript source executed by programmatic tool calling. - - `type: "function_call"` + - `fingerprint: string` - The type of the function tool call. Always `function_call`. + Opaque program replay fingerprint that must be round-tripped. - - `"function_call"` + - `type: "program"` - - `id: optional string` + The item type. Always `program`. - The unique ID of the function tool call. + - `"program"` - `agent: optional object { agent_name }` @@ -212694,394 +213141,423 @@ 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` + - `ProgramOutput object { id, call_id, result, 3 more }` - The call ID of the program item that produced this tool call. + - `id: string` - - `type: "program"` + The unique ID of this program output item. - - `"program"` + - `call_id: string` - - `namespace: optional string` + The call ID of the program item. - The namespace of the function to run. + - `result: string` - - `status: optional "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. - `"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. + - `type: "program_output"` - - `output: string or BetaResponseFunctionCallOutputItemList` + The item type. Always `program_output`. - Text, image, or file output of the function tool call. + - `"program_output"` - - `string` + - `agent: optional object { agent_name }` - A JSON string of the output of the function tool call. + The agent that produced this item. - - `BetaResponseFunctionCallOutputItemList = array of BetaResponseFunctionCallOutputItem` + - `agent_name: string` - An array of content outputs (text, image, file) for the function tool call. + The canonical name of the agent that produced this item. - - `type: "function_call_output"` +- `instructions: optional string` - The type of the function tool call output. Always `function_call_output`. + 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. - - `"function_call_output"` +- `model: optional string` - - `id: optional 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 unique ID of the function tool call output. Populated when this item is returned via API. +- `parallel_tool_calls: optional boolean` - - `agent: optional object { agent_name }` + Whether to allow the model to run tool calls in parallel. - The agent that produced this item. +- `personality: optional string or "friendly" or "pragmatic"` - - `agent_name: string` + 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 canonical name of the agent that produced this item. + - `string` - - `caller: optional object { type } or object { caller_id, type }` + - `"friendly" or "pragmatic"` - The execution context that produced this tool call. + 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. - - `Direct object { type }` + - `"friendly"` - - `type: "direct"` + - `"pragmatic"` - The caller type. Always `direct`. +- `previous_response_id: optional string` - - `"direct"` + 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`. - - `Program object { caller_id, type }` +- `reasoning: optional object { context, effort, generate_summary, 2 more }` - - `caller_id: string` + **gpt-5 and o-series models only** 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. + When returned on a response, this is the effective reasoning context mode + used for the response. - The caller type. Always `program`. + - `"auto"` - - `"program"` + - `"current_turn"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"all_turns"` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + - `effort: optional "none" or "minimal" or "low" or 4 more` - - `"in_progress"` + 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. - - `"completed"` + - `"none"` - - `"incomplete"` + - `"minimal"` - - `AgentMessage object { author, content, recipient, 3 more }` + - `"low"` - A message routed between agents. + - `"medium"` - - `author: string` + - `"high"` - The sending agent identity. + - `"xhigh"` - - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` + - `"max"` - Plaintext, image, or encrypted content sent between agents. + - `generate_summary: optional "auto" or "concise" or "detailed"` - - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` + **Deprecated:** use `summary` instead. - A text 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`. - - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` + - `"auto"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `"concise"` - - `EncryptedContent object { encrypted_content, type }` + - `"detailed"` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `mode: optional string or "standard" or "pro"` - - `encrypted_content: string` + Controls the reasoning execution mode for the request. - Opaque encrypted content. + When returned on a response, this is the effective execution mode. - - `type: "encrypted_content"` + - `string` - The type of the input item. Always `encrypted_content`. + - `"standard" or "pro"` - - `"encrypted_content"` + Controls the reasoning execution mode for the request. - - `recipient: string` + When returned on a response, this is the effective execution mode. - The destination agent identity. + - `"standard"` - - `type: "agent_message"` + - `"pro"` - The item type. Always `agent_message`. + - `summary: optional "auto" or "concise" or "detailed"` - - `"agent_message"` + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - - `id: optional string` + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - The unique ID of this agent message item. + - `"auto"` - - `agent: optional object { agent_name }` + - `"concise"` - The agent that produced this item. + - `"detailed"` - - `agent_name: string` +- `text: optional object { format, verbosity }` - The canonical name of the agent that produced this item. + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - - `MultiAgentCall object { action, arguments, call_id, 3 more }` + - [Text inputs and outputs](/docs/guides/text) + - [Structured Outputs](/docs/guides/structured-outputs) - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `format: optional BetaResponseFormatTextConfig` - The multi-agent action that was executed. + An object specifying the format that the model must output. - - `"spawn_agent"` + 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). - - `"interrupt_agent"` + The default format is `{ "type": "text" }` with no additional options. - - `"list_agents"` + **Not recommended for gpt-4o and newer models:** - - `"send_message"` + 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. - - `"followup_task"` + - `Text 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. + - `BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` - - `type: "multi_agent_call"` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - The item type. Always `multi_agent_call`. + - `name: string` - - `"multi_agent_call"` + 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. - - `id: optional string` + - `schema: map[unknown]` - The unique ID of this multi-agent call. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `agent: optional object { agent_name }` + - `type: "json_schema"` - The agent that produced this item. + The type of response format being defined. Always `json_schema`. - - `agent_name: string` + - `"json_schema"` - The canonical name of the agent that produced this item. + - `description: optional string` - - `MultiAgentCallOutput object { action, call_id, output, 3 more }` + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `strict: optional boolean` - The multi-agent action that produced this result. + 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). - - `"spawn_agent"` + - `JSONObject object { type }` - - `"interrupt_agent"` + 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. - - `"list_agents"` + - `type: "json_object"` - - `"send_message"` + The type of response format being defined. Always `json_object`. - - `"followup_task"` + - `"json_object"` - - `"wait_agent"` + - `verbosity: optional "low" or "medium" or "high"` - - `call_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 unique ID of the multi-agent call. + - `"low"` - - `output: array of object { text, type, annotations }` + - `"medium"` - Text output returned by the multi-agent action. + - `"high"` - - `text: string` +- `tool_choice: optional BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` - The text content. + Controls which tool the model should use, if any. - - `type: "output_text"` + - `BetaToolChoiceOptions = "none" or "auto" or "required"` - The content type. Always `output_text`. + Controls which (if any) tool is called by the model. - - `"output_text"` + `none` means the model will not call any tool and instead generates a message. - - `annotations: optional array of object { file_id, filename, index, type } or array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` + `auto` means the model can pick between generating a message or calling one or + more tools. - Citations associated with the text content. + `required` means the model must call one or more tools. - - `array of object { file_id, filename, index, type }` + - `"none"` - - `file_id: string` + - `"auto"` - The ID of the file. + - `"required"` - - `filename: string` + - `BetaToolChoiceAllowed object { mode, tools, type }` - The filename of the file cited. + Constrains the tools available to the model to a pre-defined set. - - `index: number` + - `mode: "auto" or "required"` - The index of the file in the list of files. + Constrains the tools available to the model to a pre-defined set. - - `type: "file_citation"` + `auto` allows the model to pick from among the allowed tools and generate a + message. - The citation type. Always `file_citation`. + `required` requires the model to call one or more of the allowed tools. - - `"file_citation"` + - `"auto"` - - `array of object { end_index, start_index, title, 2 more }` + - `"required"` - - `end_index: number` + - `tools: array of map[unknown]` - The index of the last character of the citation in the message. + A list of tool definitions that the model should be allowed to call. - - `start_index: number` + For the Responses API, the list of tool definitions might look like: - The index of the first character of the citation in the message. + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - - `title: string` + - `type: "allowed_tools"` - The title of the cited resource. + Allowed tool configuration type. Always `allowed_tools`. - - `type: "url_citation"` + - `"allowed_tools"` - The citation type. Always `url_citation`. + - `BetaToolChoiceTypes object { type }` - - `"url_citation"` + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](/docs/guides/tools). - - `url: string` + - `type: "file_search" or "web_search_preview" or "computer" or 5 more` - The URL of the cited resource. + The type of hosted tool the model should to use. Learn more about + [built-in tools](/docs/guides/tools). - - `array of object { container_id, end_index, file_id, 3 more }` + Allowed values are: - - `container_id: string` + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - The ID of the container. + - `"file_search"` - - `end_index: number` + - `"web_search_preview"` - The index of the last character of the citation in the message. + - `"computer"` - - `file_id: string` + - `"computer_use_preview"` - The ID of the container file. + - `"computer_use"` - - `filename: string` + - `"web_search_preview_2025_03_11"` - The filename of the container file cited. + - `"image_generation"` - - `start_index: number` + - `"code_interpreter"` - The index of the first character of the citation in the message. + - `BetaToolChoiceFunction object { name, type }` - - `type: "container_file_citation"` + Use this option to force the model to call a specific function. - The citation type. Always `container_file_citation`. + - `name: string` - - `"container_file_citation"` + The name of the function to call. - - `type: "multi_agent_call_output"` + - `type: "function"` - The item type. Always `multi_agent_call_output`. + For function calling, the type is always `function`. - - `"multi_agent_call_output"` + - `"function"` - - `id: optional string` + - `BetaToolChoiceMcp object { server_label, type, name }` - The unique ID of this multi-agent call output. + Use this option to force the model to call a specific tool on a remote MCP server. - - `agent: optional object { agent_name }` + - `server_label: string` - The agent that produced this item. + The label of the MCP server to use. - - `agent_name: string` + - `type: "mcp"` - The canonical name of the agent that produced this item. + For MCP tools, the type is always `mcp`. - - `ToolSearchCall object { arguments, type, id, 4 more }` + - `"mcp"` - - `arguments: unknown` + - `name: optional string` - The arguments supplied to the tool search call. + The name of the tool to call on the server. - - `type: "tool_search_call"` + - `BetaToolChoiceCustom object { name, type }` - The item type. Always `tool_search_call`. + Use this option to force the model to call a specific custom tool. - - `"tool_search_call"` + - `name: string` - - `id: optional string` + The name of the custom tool to call. - The unique ID of this tool search call. + - `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` + - `BetaSpecificProgrammaticToolCallingParam object { type }` - The canonical name of the agent that produced this item. + - `type: "programmatic_tool_calling"` - - `call_id: optional string` + The tool to call. Always `programmatic_tool_calling`. - The unique ID of the tool search call generated by the model. + - `"programmatic_tool_calling"` - - `execution: optional "server" or "client"` + - `BetaToolChoiceApplyPatch object { type }` - Whether tool search was executed by the server or by the client. + Forces the model to call the apply_patch tool when executing a tool call. - - `"server"` + - `type: "apply_patch"` - - `"client"` + The tool to call. Always `apply_patch`. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"apply_patch"` - The status of the tool search call. + - `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`. - - `ToolSearchOutput object { tools, type, id, 4 more }` + - `"shell"` - - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` +- `tools: optional array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - The loaded tool definitions returned by the tool search output. + 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. - `Function object { name, parameters, strict, 5 more }` @@ -213344,7 +213820,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-web-search). + [web search tool](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -213404,7 +213880,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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](https://platform.openai.com/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -213456,7 +213932,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -213648,19 +214124,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `background: optional "transparent" or "opaque" or "auto"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. - - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. - - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - `"transparent"` @@ -213689,13 +214154,13 @@ curl -X POST https://api.openai.com/v1/responses/compact \ Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `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-2" or 3 more` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` The image generation model to use. Default: `gpt-image-1`. @@ -213703,14 +214168,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"gpt-image-1-mini"` - - `"gpt-image-2"` - - - `"gpt-image-2-2026-04-21"` - - `"gpt-image-1.5"` - - `"chatgpt-image-latest"` - - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -213807,7 +214266,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -213921,7 +214380,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -214089,18282 +214548,19937 @@ 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"` - - - `id: optional string` - - The unique ID of this 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. - - - `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"` - - The role that provided the additional tools. Only `developer` is supported. - - - `"developer"` - - - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - - A list of additional tools made available at this item. - - - `Function object { name, parameters, strict, 5 more }` - - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - - `name: string` - - The name of the function to call. - - - `parameters: map[unknown]` - - A JSON schema object describing the parameters of the function. - - - `strict: boolean` - - Whether strict parameter validation is enforced for this function tool. - - - `type: "function"` - - The type of the function tool. Always `function`. - - - `"function"` - - - `allowed_callers: optional array of "direct" or "programmatic"` - - The tool invocation context(s). - - - `"direct"` - - - `"programmatic"` - - - `defer_loading: optional boolean` - - Whether this function is deferred and loaded via tool search. - - - `description: optional string` - - A description of the function. Used by the model to determine whether or not to call the function. - - - `output_schema: optional map[unknown]` - - A JSON schema object describing the JSON value encoded in string outputs for this function. - - - `FileSearch object { type, vector_store_ids, filters, 2 more }` - - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - - `type: "file_search"` - - The type of the file search tool. Always `file_search`. - - - `"file_search"` - - - `vector_store_ids: array of string` - - The IDs of the vector stores to search. - - - `filters: optional 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"` +- `truncation: optional "auto" or "disabled"` - - `"nin"` + 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. - - `value: string or number or boolean or array of string or number` + - `"auto"` - The value to compare against the attribute key; supports string, number, or boolean types. + - `"disabled"` - - `string` +### Returns - - `number` +- `input_tokens: number` - - `boolean` +- `object: "response.input_tokens"` - - `array of string or number` + - `"response.input_tokens"` - - `string` +### Example - - `number` +```http +curl https://api.openai.com/v1/responses/input_tokens \ + -X POST \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - - `CompoundFilter object { filters, type }` +#### Response - Combine multiple filters using `and` or `or`. +```json +{ + "input_tokens": 123, + "object": "response.input_tokens" +} +``` - - `filters: array of object { key, type, value } or unknown` +### Example - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. +```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." + }' +``` - - `ComparisonFilter object { key, type, value }` +#### Response - A filter used to compare a specified attribute key to a given value using a defined comparison operation. +```json +{ + "object": "response.input_tokens", + "input_tokens": 11 +} +``` - - `key: string` +## Domain Types - The key to compare against the value. +### Input Token Count Response - - `type: "eq" or "ne" or "gt" or 5 more` +- `InputTokenCountResponse object { input_tokens, object }` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `input_tokens: 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 + - `object: "response.input_tokens"` - - `"eq"` + - `"response.input_tokens"` - - `"ne"` +# ChatKit - - `"gt"` +## Domain Types - - `"gte"` +### ChatKit Workflow - - `"lt"` +- `ChatKitWorkflow object { id, state_variables, tracing, version }` - - `"lte"` + Workflow metadata and state returned for the session. - - `"in"` + - `id: string` - - `"nin"` + Identifier of the workflow backing the session. - - `value: string or number or boolean or array of string or number` + - `state_variables: map[string or boolean or number]` - The value to compare against the attribute key; supports string, number, or boolean types. + State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided. - `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](https://platform.openai.com/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](https://platform.openai.com/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](https://platform.openai.com/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"` - - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. - - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. - - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. - - - `"transparent"` - - - `"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-2" or 3 more` - - The image generation model to use. Default: `gpt-image-1`. - - - `string` - - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` - - The image generation model to use. Default: `gpt-image-1`. - - - `"gpt-image-1"` - - - `"gpt-image-1-mini"` - - - `"gpt-image-2"` - - - `"gpt-image-2-2026-04-21"` - - - `"gpt-image-1.5"` - - - `"chatgpt-image-latest"` - - - `moderation: optional "auto" or "low"` - - Moderation level for the generated image. Default: `auto`. - - - `"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"` + - `tracing: object { enabled }` - 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`. + Tracing settings applied to the workflow. - - `string` + - `enabled: boolean` - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + Indicates whether tracing is enabled. - 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`. + - `version: string` - - `"1024x1024"` + Specific workflow version used for the session. Defaults to null when using the latest deployment. - - `"1024x1536"` +# Sessions - - `"1536x1024"` +## Cancel chat session - - `"auto"` +**post** `/chatkit/sessions/{session_id}/cancel` - - `LocalShell object { type }` +Cancel an active ChatKit session and return its most recent metadata. - A tool that allows the model to execute shell commands in a local environment. +Cancelling prevents new requests from using the issued client secret. - - `type: "local_shell"` +### Path Parameters - The type of the local shell tool. Always `local_shell`. +- `session_id: string` - - `"local_shell"` +### Returns - - `Shell object { type, allowed_callers, environment }` +- `ChatSession object { id, chatkit_configuration, client_secret, 7 more }` - A tool that allows the model to execute shell commands. + Represents a ChatKit session and its resolved configuration. - - `type: "shell"` + - `id: string` - The type of the shell tool. Always `shell`. + Identifier for the ChatKit session. - - `"shell"` + - `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` - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + Whether automatic thread titling is enabled. - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `file_upload: ChatSessionFileUpload` - - `BetaLocalEnvironment object { type, skills }` + Upload settings for the session. - - `BetaContainerReference object { container_id, type }` + - `enabled: boolean` - - `Custom object { name, type, allowed_callers, 3 more }` + Indicates if uploads are enabled for the session. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `max_file_size: number` - - `name: string` + Maximum upload size in megabytes. - The name of the custom tool, used to identify it in tool calls. + - `max_files: number` - - `type: "custom"` + Maximum number of uploads allowed during the session. - The type of the custom tool. Always `custom`. + - `history: ChatSessionHistory` - - `"custom"` + History retention configuration. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `enabled: boolean` - The tool invocation context(s). + Indicates if chat history is persisted for the session. - - `"direct"` + - `recent_threads: number` - - `"programmatic"` + Number of prior threads surfaced in history views. Defaults to null when all history is retained. - - `defer_loading: optional boolean` + - `client_secret: string` - Whether this tool should be deferred and discovered via tool search. + Ephemeral client secret that authenticates session requests. - - `description: optional string` + - `expires_at: number` - Optional description of the custom tool, used to provide more context. + Unix timestamp (in seconds) for when the session expires. - - `format: optional object { type } or object { definition, syntax, type }` + - `max_requests_per_1_minute: number` - The input format for the custom tool. Default is unconstrained text. + Convenience copy of the per-minute request limit. - - `Text object { type }` + - `object: "chatkit.session"` - Unconstrained free-form text. + Type discriminator that is always `chatkit.session`. - - `type: "text"` + - `"chatkit.session"` - Unconstrained text format. Always `text`. + - `rate_limits: ChatSessionRateLimits` - - `"text"` + Resolved rate limit values. - - `Grammar object { definition, syntax, type }` + - `max_requests_per_1_minute: number` - A grammar defined by the user. + Maximum allowed requests per one-minute window. - - `definition: string` + - `status: ChatSessionStatus` - The grammar definition. + Current lifecycle state of the session. - - `syntax: "lark" or "regex"` + - `"active"` - The syntax of the grammar definition. One of `lark` or `regex`. + - `"expired"` - - `"lark"` + - `"cancelled"` - - `"regex"` + - `user: string` - - `type: "grammar"` + User identifier associated with the session. - Grammar format. Always `grammar`. + - `workflow: ChatKitWorkflow` - - `"grammar"` + Workflow metadata for the session. - - `Namespace object { description, name, tools, type }` + - `id: string` - Groups function/custom tools under a shared namespace. + Identifier of the workflow backing the session. - - `description: string` + - `state_variables: map[string or boolean or number]` - A description of the namespace shown to the model. + State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided. - - `name: string` + - `string` - The namespace name used in tool calls (for example, `crm`). + - `boolean` - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + - `number` - The function/custom tools available inside this namespace. + - `tracing: object { enabled }` - - `Function object { name, type, allowed_callers, 5 more }` + Tracing settings applied to the workflow. - - `name: string` + - `enabled: boolean` - - `type: "function"` + Indicates whether tracing is enabled. - - `"function"` + - `version: string` - - `allowed_callers: optional array of "direct" or "programmatic"` + Specific workflow version used for the session. Defaults to null when using the latest deployment. - The tool invocation context(s). +### Example - - `"direct"` +```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" +``` - - `"programmatic"` +#### Response - - `defer_loading: optional boolean` +```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" + } +} +``` - Whether this function should be deferred and discovered via tool search. +### Example - - `description: optional string` +```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" +``` - - `output_schema: optional map[unknown]` +#### Response - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. +```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 +} +``` - - `parameters: optional unknown` +## Create ChatKit session - - `strict: optional boolean` +**post** `/chatkit/sessions` - 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. +Create a ChatKit session. - - `Custom object { name, type, allowed_callers, 3 more }` +### Body Parameters - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) +- `user: string` - - `name: string` + A free-form string that identifies your end user; ensures this Session can access other objects that have the same `user` scope. - The name of the custom tool, used to identify it in tool calls. +- `workflow: ChatSessionWorkflowParam` - - `type: "custom"` + Workflow that powers the session. - The type of the custom tool. Always `custom`. + - `id: string` - - `"custom"` + Identifier for the workflow invoked by the session. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `state_variables: optional map[string or boolean or number]` - The tool invocation context(s). + 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. - - `"direct"` + - `string` - - `"programmatic"` + - `boolean` - - `defer_loading: optional boolean` + - `number` - Whether this tool should be deferred and discovered via tool search. + - `tracing: optional object { enabled }` - - `description: optional string` + Optional tracing overrides for the workflow invocation. When omitted, tracing is enabled by default. - Optional description of the custom tool, used to provide more context. + - `enabled: optional boolean` - - `format: optional object { type } or object { definition, syntax, type }` + Whether tracing is enabled during the session. Defaults to true. - The input format for the custom tool. Default is unconstrained text. + - `version: optional string` - - `Text object { type }` + Specific workflow version to run. Defaults to the latest deployed version. - Unconstrained free-form text. +- `chatkit_configuration: optional ChatSessionChatKitConfigurationParam` - - `type: "text"` + Optional overrides for ChatKit runtime configuration features - Unconstrained text format. Always `text`. + - `automatic_thread_titling: optional object { enabled }` - - `"text"` + Configuration for automatic thread titling. When omitted, automatic thread titling is enabled by default. - - `Grammar object { definition, syntax, type }` + - `enabled: optional boolean` - A grammar defined by the user. + Enable automatic thread title generation. Defaults to true. - - `definition: string` + - `file_upload: optional object { enabled, max_file_size, max_files }` - The grammar definition. + Configuration for upload enablement and limits. When omitted, uploads are disabled by default (max_files 10, max_file_size 512 MB). - - `syntax: "lark" or "regex"` + - `enabled: optional boolean` - The syntax of the grammar definition. One of `lark` or `regex`. + Enable uploads for this session. Defaults to false. - - `"lark"` + - `max_file_size: optional number` - - `"regex"` + Maximum size in megabytes for each uploaded file. Defaults to 512 MB, which is the maximum allowable size. - - `type: "grammar"` + - `max_files: optional number` - Grammar format. Always `grammar`. + Maximum number of files that can be uploaded to the session. Defaults to 10. - - `"grammar"` + - `history: optional object { enabled, recent_threads }` - - `type: "namespace"` + Configuration for chat history retention. When omitted, history is enabled by default with no limit on recent_threads (null). - The type of the tool. Always `namespace`. + - `enabled: optional boolean` - - `"namespace"` + Enables chat users to access previous ChatKit threads. Defaults to true. - - `ToolSearch object { type, description, execution, parameters }` + - `recent_threads: optional number` - Hosted or BYOT tool search configuration for deferred tools. + Number of recent ChatKit threads users have access to. Defaults to unlimited when unset. - - `type: "tool_search"` +- `expires_after: optional ChatSessionExpiresAfterParam` - The type of the tool. Always `tool_search`. + Optional override for session expiration timing in seconds from creation. Defaults to 10 minutes. - - `"tool_search"` + - `anchor: "created_at"` - - `description: optional string` + Base timestamp used to calculate expiration. Currently fixed to `created_at`. - Description shown to the model for a client-executed tool search tool. + - `"created_at"` - - `execution: optional "server" or "client"` + - `seconds: number` - Whether tool search is executed by the server or by the client. + Number of seconds after the anchor when the session expires. - - `"server"` +- `rate_limits: optional ChatSessionRateLimitsParam` - - `"client"` + Optional override for per-minute request limits. When omitted, defaults to 10. - - `parameters: optional unknown` + - `max_requests_per_1_minute: optional number` - Parameter schema for a client-executed tool search tool. + Maximum number of requests allowed per minute for the session. Defaults to 10. - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` +### Returns - 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). +- `ChatSession object { id, chatkit_configuration, client_secret, 7 more }` - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + Represents a ChatKit session and its resolved configuration. - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `id: string` - - `"web_search_preview"` + Identifier for the ChatKit session. - - `"web_search_preview_2025_03_11"` + - `chatkit_configuration: ChatSessionChatKitConfiguration` - - `search_content_types: optional array of "text" or "image"` + Resolved ChatKit feature configuration for the session. - - `"text"` + - `automatic_thread_titling: ChatSessionAutomaticThreadTitling` - - `"image"` + Automatic thread titling preferences. - - `search_context_size: optional "low" or "medium" or "high"` + - `enabled: 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 automatic thread titling is enabled. - - `"low"` + - `file_upload: ChatSessionFileUpload` - - `"medium"` + Upload settings for the session. - - `"high"` + - `enabled: boolean` - - `user_location: optional object { type, city, country, 2 more }` + Indicates if uploads are enabled for the session. - The user's location. + - `max_file_size: number` - - `type: "approximate"` + Maximum upload size in megabytes. - The type of location approximation. Always `approximate`. + - `max_files: number` - - `"approximate"` + Maximum number of uploads allowed during the session. - - `city: optional string` + - `history: ChatSessionHistory` - Free text input for the city of the user, e.g. `San Francisco`. + History retention configuration. - - `country: optional string` + - `enabled: boolean` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + Indicates if chat history is persisted for the session. - - `region: optional string` + - `recent_threads: number` - Free text input for the region of the user, e.g. `California`. + Number of prior threads surfaced in history views. Defaults to null when all history is retained. - - `timezone: optional string` + - `client_secret: string` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + Ephemeral client secret that authenticates session requests. - - `ApplyPatch object { type, allowed_callers }` + - `expires_at: number` - Allows the assistant to create, delete, or update files using unified diffs. + Unix timestamp (in seconds) for when the session expires. - - `type: "apply_patch"` + - `max_requests_per_1_minute: number` - The type of the tool. Always `apply_patch`. + Convenience copy of the per-minute request limit. - - `"apply_patch"` + - `object: "chatkit.session"` - - `allowed_callers: optional array of "direct" or "programmatic"` + Type discriminator that is always `chatkit.session`. - The tool invocation context(s). + - `"chatkit.session"` - - `"direct"` + - `rate_limits: ChatSessionRateLimits` - - `"programmatic"` + Resolved rate limit values. - - `type: "additional_tools"` + - `max_requests_per_1_minute: number` - The item type. Always `additional_tools`. + Maximum allowed requests per one-minute window. - - `"additional_tools"` + - `status: ChatSessionStatus` - - `id: optional string` + Current lifecycle state of the session. - The unique ID of this additional tools item. + - `"active"` - - `agent: optional object { agent_name }` + - `"expired"` - The agent that produced this item. + - `"cancelled"` - - `agent_name: string` + - `user: string` - The canonical name of the agent that produced this item. + User identifier associated with the session. - - `Reasoning object { id, summary, type, 4 more }` + - `workflow: ChatKitWorkflow` - 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](https://platform.openai.com/docs/guides/conversation-state). + Workflow metadata for the session. - `id: string` - The unique identifier of the reasoning content. + Identifier of the workflow backing the session. - - `summary: array of object { text, type }` + - `state_variables: map[string or boolean or number]` - Reasoning summary content. + State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided. - - `text: string` + - `string` - A summary of the reasoning output from the model so far. + - `boolean` - - `type: "summary_text"` + - `number` - The type of the object. Always `summary_text`. + - `tracing: object { enabled }` - - `"summary_text"` + Tracing settings applied to the workflow. - - `type: "reasoning"` + - `enabled: boolean` - The type of the object. Always `reasoning`. + Indicates whether tracing is enabled. - - `"reasoning"` + - `version: string` - - `agent: optional object { agent_name }` + Specific workflow version used for the session. Defaults to null when using the latest deployment. - The agent that produced this item. +### Example - - `agent_name: string` +```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" + } + }' +``` - The canonical name of the agent that produced this item. +#### Response - - `content: optional array of object { text, type }` +```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" + } +} +``` - Reasoning text content. +### Example - - `text: string` +```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 + }' +``` - The reasoning text from the model. +#### Response - - `type: "reasoning_text"` +```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 type of the reasoning text. Always `reasoning_text`. +# Threads - - `"reasoning_text"` +## List ChatKit thread items - - `encrypted_content: optional string` +**get** `/chatkit/threads/{thread_id}/items` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. +List items that belong to a ChatKit thread. - - `status: optional "in_progress" or "completed" or "incomplete"` +### Path Parameters - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. +- `thread_id: string` - - `"in_progress"` +### Query Parameters - - `"completed"` +- `after: optional string` - - `"incomplete"` + List items created after this thread item ID. Defaults to null for the first page. - - `Compaction object { encrypted_content, type, id, agent }` +- `before: optional string` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + List items created before this thread item ID. Defaults to null for the newest results. - - `encrypted_content: string` +- `limit: optional number` - The encrypted content of the compaction summary. + Maximum number of thread items to return. Defaults to 20. - - `type: "compaction"` +- `order: optional "asc" or "desc"` - The type of the item. Always `compaction`. + Sort order for results by creation time. Defaults to `desc`. - - `"compaction"` + - `"asc"` - - `id: optional string` + - `"desc"` - The ID of the compaction item. +### Returns - - `agent: optional object { agent_name }` +- `ChatKitThreadItemList object { data, first_id, has_more, 2 more }` - The agent that produced this item. + A paginated list of thread items rendered for the ChatKit API. - - `agent_name: string` + - `data: array of ChatKitThreadUserMessageItem or ChatKitThreadAssistantMessageItem or ChatKitWidgetItem or 3 more` - The canonical name of the agent that produced this item. + A list of items - - `ImageGenerationCall object { id, result, status, 2 more }` + - `ChatKitThreadUserMessageItem object { id, attachments, content, 5 more }` - An image generation request made by the model. + User-authored messages within a thread. - `id: string` - The unique ID of the image generation call. - - - `result: string` + Identifier of the thread item. - The generated image encoded in base64. + - `attachments: array of ChatKitAttachment` - - `status: "in_progress" or "completed" or "generating" or "failed"` + Attachments associated with the user message. Defaults to an empty list. - The status of the image generation call. + - `id: string` - - `"in_progress"` + Identifier for the attachment. - - `"completed"` + - `mime_type: string` - - `"generating"` + MIME type of the attachment. - - `"failed"` + - `name: string` - - `type: "image_generation_call"` + Original display name for the attachment. - The type of the image generation call. Always `image_generation_call`. + - `preview_url: string` - - `"image_generation_call"` + Preview URL for rendering the attachment inline. - - `agent: optional object { agent_name }` + - `type: "image" or "file"` - The agent that produced this item. + Attachment discriminator. - - `agent_name: string` + - `"image"` - The canonical name of the agent that produced this item. + - `"file"` - - `CodeInterpreterCall object { id, code, container_id, 4 more }` + - `content: array of object { text, type } or object { text, type }` - A tool call to run code. + Ordered content elements supplied by the user. - - `id: string` + - `InputText object { text, type }` - The unique ID of the code interpreter tool call. + Text block that a user contributed to the thread. - - `code: string` + - `text: string` - The code to run, or null if not available. + Plain-text content supplied by the user. - - `container_id: string` + - `type: "input_text"` - The ID of the container used to run the code. + Type discriminator that is always `input_text`. - - `outputs: array of object { logs, type } or object { type, url }` + - `"input_text"` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `QuotedText object { text, type }` - - `Logs object { logs, type }` + Quoted snippet that the user referenced in their message. - The logs output from the code interpreter. + - `text: string` - - `logs: string` + Quoted text content. - The logs output from the code interpreter. + - `type: "quoted_text"` - - `type: "logs"` + Type discriminator that is always `quoted_text`. - The type of the output. Always `logs`. + - `"quoted_text"` - - `"logs"` + - `created_at: number` - - `Image object { type, url }` + Unix timestamp (in seconds) for when the item was created. - The image output from the code interpreter. + - `inference_options: object { model, tool_choice }` - - `type: "image"` + Inference overrides applied to the message. Defaults to null when unset. - The type of the output. Always `image`. + - `model: string` - - `"image"` + Model name that generated the response. Defaults to null when using the session default. - - `url: string` + - `tool_choice: object { id }` - The URL of the image output from the code interpreter. + Preferred tool to invoke. Defaults to null when ChatKit should auto-select. - - `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`. + Identifier of the requested tool. - - `"in_progress"` + - `object: "chatkit.thread_item"` - - `"completed"` + Type discriminator that is always `chatkit.thread_item`. - - `"incomplete"` + - `"chatkit.thread_item"` - - `"interpreting"` + - `thread_id: string` - - `"failed"` + Identifier of the parent thread. - - `type: "code_interpreter_call"` + - `type: "chatkit.user_message"` - The type of the code interpreter tool call. Always `code_interpreter_call`. + - `"chatkit.user_message"` - - `"code_interpreter_call"` + - `ChatKitThreadAssistantMessageItem object { id, content, created_at, 3 more }` - - `agent: optional object { agent_name }` + Assistant-authored message within a thread. - The agent that produced this item. + - `id: string` - - `agent_name: string` + Identifier of the thread item. - The canonical name of the agent that produced this item. + - `content: array of ChatKitResponseOutputText` - - `LocalShellCall object { id, action, call_id, 3 more }` + Ordered assistant response segments. - A tool call to run a command on the local shell. + - `annotations: array of object { source, type } or object { source, type }` - - `id: string` + Ordered list of annotations attached to the response text. - The unique ID of the local shell call. + - `File object { source, type }` - - `action: object { command, env, type, 3 more }` + Annotation that references an uploaded file. - Execute a shell command on the server. + - `source: object { filename, type }` - - `command: array of string` + File attachment referenced by the annotation. - The command to run. + - `filename: string` - - `env: map[string]` + Filename referenced by the annotation. - Environment variables to set for the command. + - `type: "file"` - - `type: "exec"` + Type discriminator that is always `file`. - The type of the local shell action. Always `exec`. + - `"file"` - - `"exec"` + - `type: "file"` - - `timeout_ms: optional number` + Type discriminator that is always `file` for this annotation. - Optional timeout in milliseconds for the command. + - `"file"` - - `user: optional string` + - `URL object { source, type }` - Optional user to run the command as. + Annotation that references a URL. - - `working_directory: optional string` + - `source: object { type, url }` - Optional working directory to run the command in. + URL referenced by the annotation. - - `call_id: string` + - `type: "url"` - The unique ID of the local shell tool call generated by the model. + Type discriminator that is always `url`. - - `status: "in_progress" or "completed" or "incomplete"` + - `"url"` - The status of the local shell call. + - `url: string` - - `"in_progress"` + URL referenced by the annotation. - - `"completed"` + - `type: "url"` - - `"incomplete"` + Type discriminator that is always `url` for this annotation. - - `type: "local_shell_call"` + - `"url"` - The type of the local shell call. Always `local_shell_call`. + - `text: string` - - `"local_shell_call"` + 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` - - `LocalShellCallOutput object { id, output, type, 2 more }` + Unix timestamp (in seconds) for when the item was created. - The output of a local shell tool call. + - `object: "chatkit.thread_item"` - - `id: string` + Type discriminator that is always `chatkit.thread_item`. - The unique ID of the local shell tool call generated by the model. + - `"chatkit.thread_item"` - - `output: string` + - `thread_id: string` - A JSON string of the output of the local shell tool call. + Identifier of the parent thread. - - `type: "local_shell_call_output"` + - `type: "chatkit.assistant_message"` - The type of the local shell tool call output. Always `local_shell_call_output`. + Type discriminator that is always `chatkit.assistant_message`. - - `"local_shell_call_output"` + - `"chatkit.assistant_message"` - - `agent: optional object { agent_name }` + - `ChatKitWidgetItem object { id, created_at, object, 3 more }` - The agent that produced this item. + Thread item that renders a widget payload. - - `agent_name: string` + - `id: string` - The canonical name of the agent that produced this item. + Identifier of the thread item. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `created_at: number` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + Unix timestamp (in seconds) for when the item was created. - - `"in_progress"` + - `object: "chatkit.thread_item"` - - `"completed"` + Type discriminator that is always `chatkit.thread_item`. - - `"incomplete"` + - `"chatkit.thread_item"` - - `ShellCall object { action, call_id, type, 5 more }` + - `thread_id: string` - A tool representing a request to execute one or more shell commands. + Identifier of the parent thread. - - `action: object { commands, max_output_length, timeout_ms }` + - `type: "chatkit.widget"` - The shell commands and limits that describe how to run the tool call. + Type discriminator that is always `chatkit.widget`. - - `commands: array of string` + - `"chatkit.widget"` - Ordered shell commands for the execution environment to run. + - `widget: string` - - `max_output_length: optional number` + Serialized widget payload rendered in the UI. - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + - `ChatKitClientToolCall object { id, arguments, call_id, 7 more }` - - `timeout_ms: optional number` + Record of a client side tool invocation initiated by the assistant. - Maximum wall-clock time in milliseconds to allow the shell commands to run. + - `id: string` - - `call_id: string` + Identifier of the thread item. - The unique ID of the shell tool call generated by the model. + - `arguments: string` - - `type: "shell_call"` + JSON-encoded arguments that were sent to the tool. - The type of the item. Always `shell_call`. + - `call_id: string` - - `"shell_call"` + Identifier for the client tool call. - - `id: optional string` + - `created_at: number` - The unique ID of the shell tool call. Populated when this item is returned via API. + Unix timestamp (in seconds) for when the item was created. - - `agent: optional object { agent_name }` + - `name: string` - The agent that produced this item. + Tool name that was invoked. - - `agent_name: string` + - `object: "chatkit.thread_item"` - The canonical name of the agent that produced this item. + Type discriminator that is always `chatkit.thread_item`. - - `caller: optional object { type } or object { caller_id, type }` + - `"chatkit.thread_item"` - The execution context that produced this tool call. + - `output: string` - - `Direct object { type }` + JSON-encoded output captured from the tool. Defaults to null while execution is in progress. - - `type: "direct"` + - `status: "in_progress" or "completed"` - The caller type. Always `direct`. + Execution status for the tool call. - - `"direct"` + - `"in_progress"` - - `Program object { caller_id, type }` + - `"completed"` - - `caller_id: string` + - `thread_id: string` - The call ID of the program item that produced this tool call. + Identifier of the parent thread. - - `type: "program"` + - `type: "chatkit.client_tool_call"` - The caller type. Always `program`. + Type discriminator that is always `chatkit.client_tool_call`. - - `"program"` + - `"chatkit.client_tool_call"` - - `environment: optional BetaLocalEnvironment or BetaContainerReference` + - `ChatKitTask object { id, created_at, heading, 5 more }` - The environment to execute the shell commands in. + Task emitted by the workflow to show progress and status updates. - - `BetaLocalEnvironment object { type, skills }` + - `id: string` - - `BetaContainerReference object { container_id, type }` + Identifier of the thread item. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `created_at: number` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + Unix timestamp (in seconds) for when the item was created. - - `"in_progress"` + - `heading: string` - - `"completed"` + Optional heading for the task. Defaults to null when not provided. - - `"incomplete"` + - `object: "chatkit.thread_item"` - - `ShellCallOutput object { call_id, output, type, 5 more }` + Type discriminator that is always `chatkit.thread_item`. - The streamed output items emitted by a shell tool call. + - `"chatkit.thread_item"` - - `call_id: string` + - `summary: string` - The unique ID of the shell tool call generated by the model. + Optional summary that describes the task. Defaults to null when omitted. - - `output: array of BetaResponseFunctionShellCallOutputContent` + - `task_type: "custom" or "thought"` - Captured chunks of stdout and stderr output, along with their associated outcomes. + Subtype for the task. - - `outcome: object { type } or object { exit_code, type }` + - `"custom"` - The exit or timeout outcome associated with this shell call. + - `"thought"` - - `stderr: string` + - `thread_id: string` - Captured stderr output for the shell call. + Identifier of the parent thread. - - `stdout: string` + - `type: "chatkit.task"` - Captured stdout output for the shell call. + Type discriminator that is always `chatkit.task`. - - `type: "shell_call_output"` + - `"chatkit.task"` - The type of the item. Always `shell_call_output`. + - `ChatKitTaskGroup object { id, created_at, object, 3 more }` - - `"shell_call_output"` + Collection of workflow tasks grouped together in the thread. - - `id: optional string` + - `id: string` - The unique ID of the shell tool call output. Populated when this item is returned via API. + Identifier of the thread item. - - `agent: optional object { agent_name }` + - `created_at: number` - The agent that produced this item. + Unix timestamp (in seconds) for when the item was created. - - `agent_name: string` + - `object: "chatkit.thread_item"` - The canonical name of the agent that produced this item. + Type discriminator that is always `chatkit.thread_item`. - - `caller: optional object { type } or object { caller_id, type }` + - `"chatkit.thread_item"` - The execution context that produced this tool call. + - `tasks: array of object { heading, summary, type }` - - `Direct object { type }` + Tasks included in the group. - - `type: "direct"` + - `heading: string` - The caller type. Always `direct`. + Optional heading for the grouped task. Defaults to null when not provided. - - `"direct"` + - `summary: string` - - `Program object { caller_id, type }` + Optional summary that describes the grouped task. Defaults to null when omitted. - - `caller_id: string` + - `type: "custom" or "thought"` - The call ID of the program item that produced this tool call. + Subtype for the grouped task. - - `type: "program"` + - `"custom"` - The caller type. Always `program`. + - `"thought"` - - `"program"` + - `thread_id: string` - - `max_output_length: optional number` + Identifier of the parent thread. - The maximum number of UTF-8 characters captured for this shell call's combined output. + - `type: "chatkit.task_group"` - - `status: optional "in_progress" or "completed" or "incomplete"` + Type discriminator that is always `chatkit.task_group`. - The status of the shell call output. + - `"chatkit.task_group"` - - `"in_progress"` + - `first_id: string` - - `"completed"` + The ID of the first item in the list. - - `"incomplete"` + - `has_more: boolean` - - `ApplyPatchCall object { call_id, operation, status, 4 more }` + Whether there are more items available. - A tool call representing a request to create, delete, or update files using diff patches. + - `last_id: string` - - `call_id: string` + The ID of the last item in the list. - The unique ID of the apply patch tool call generated by the model. + - `object: "list"` - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + The type of object returned, must be `list`. - The specific create, delete, or update instruction for the apply_patch tool call. + - `"list"` - - `CreateFile object { diff, path, type }` +### Example - Instruction for creating a new file via the apply_patch tool. +```http +curl https://api.openai.com/v1/chatkit/threads/$THREAD_ID/items \ + -H 'OpenAI-Beta: chatkit_beta=v1' \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - - `diff: string` +#### Response - Unified diff content to apply when creating the file. +```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" +} +``` - - `path: string` +### Example - Path of the file to create relative to the workspace root. +```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: "create_file"` +#### Response - The operation type. Always `create_file`. +```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" +} +``` - - `"create_file"` +## Retrieve ChatKit thread - - `DeleteFile object { path, type }` +**get** `/chatkit/threads/{thread_id}` - Instruction for deleting an existing file via the apply_patch tool. +Retrieve a ChatKit thread by its identifier. - - `path: string` +### Path Parameters - Path of the file to delete relative to the workspace root. +- `thread_id: string` - - `type: "delete_file"` +### Returns - The operation type. Always `delete_file`. +- `ChatKitThread object { id, created_at, object, 3 more }` - - `"delete_file"` + Represents a ChatKit thread and its current status. - - `UpdateFile object { diff, path, type }` + - `id: string` - Instruction for updating an existing file via the apply_patch tool. + Identifier of the thread. - - `diff: string` + - `created_at: number` - Unified diff content to apply to the existing file. + Unix timestamp (in seconds) for when the thread was created. - - `path: string` + - `object: "chatkit.thread"` - Path of the file to update relative to the workspace root. + Type discriminator that is always `chatkit.thread`. - - `type: "update_file"` + - `"chatkit.thread"` - The operation type. Always `update_file`. + - `status: object { type } or object { reason, type } or object { reason, type }` - - `"update_file"` + Current status for the thread. Defaults to `active` for newly created threads. - - `status: "in_progress" or "completed"` + - `Active object { type }` - The status of the apply patch tool call. One of `in_progress` or `completed`. + Indicates that a thread is active. - - `"in_progress"` + - `type: "active"` - - `"completed"` + Status discriminator that is always `active`. - - `type: "apply_patch_call"` + - `"active"` - The type of the item. Always `apply_patch_call`. + - `Locked object { reason, type }` - - `"apply_patch_call"` + Indicates that a thread is locked and cannot accept new input. - - `id: optional string` + - `reason: string` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + Reason that the thread was locked. Defaults to null when no reason is recorded. - - `agent: optional object { agent_name }` + - `type: "locked"` - The agent that produced this item. + Status discriminator that is always `locked`. - - `agent_name: string` + - `"locked"` - The canonical name of the agent that produced this item. + - `Closed object { reason, type }` - - `caller: optional object { type } or object { caller_id, type }` + Indicates that a thread has been closed. - The execution context that produced this tool call. + - `reason: string` - - `Direct object { type }` + Reason that the thread was closed. Defaults to null when no reason is recorded. - - `type: "direct"` + - `type: "closed"` - The caller type. Always `direct`. + Status discriminator that is always `closed`. - - `"direct"` + - `"closed"` - - `Program object { caller_id, type }` + - `title: string` - - `caller_id: string` + Optional human-readable title for the thread. Defaults to null when no title has been generated. - The call ID of the program item that produced this tool call. + - `user: string` - - `type: "program"` + Free-form string that identifies your end user who owns the thread. - The caller type. Always `program`. +### Example - - `"program"` +```http +curl https://api.openai.com/v1/chatkit/threads/$THREAD_ID \ + -H 'OpenAI-Beta: chatkit_beta=v1' \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - - `ApplyPatchCallOutput object { call_id, status, type, 4 more }` +#### Response - The streamed output emitted by an apply patch tool call. +```json +{ + "id": "cthr_def456", + "created_at": 1712345600, + "object": "chatkit.thread", + "status": { + "type": "active" + }, + "title": "Demo feedback", + "user": "user_456" +} +``` - - `call_id: string` +### Example - The unique ID of the apply patch tool call generated by the model. +```http +curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ + -H "OpenAI-Beta: chatkit_beta=v1" \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - - `status: "completed" or "failed"` +#### Response - The status of the apply patch tool call output. One of `completed` or `failed`. +```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 + } +} +``` - - `"completed"` +## Delete ChatKit thread - - `"failed"` +**delete** `/chatkit/threads/{thread_id}` - - `type: "apply_patch_call_output"` +Delete a ChatKit thread along with its items and stored attachments. - The type of the item. Always `apply_patch_call_output`. +### Path Parameters - - `"apply_patch_call_output"` +- `thread_id: string` - - `id: optional string` +### Returns - The unique ID of the apply patch tool call output. Populated when this item is returned via API. +- `id: string` - - `agent: optional object { agent_name }` + Identifier of the deleted thread. - The agent that produced this item. +- `deleted: boolean` - - `agent_name: string` + Indicates that the thread has been deleted. - The canonical name of the agent that produced this item. +- `object: "chatkit.thread.deleted"` - - `caller: optional object { type } or object { caller_id, type }` + Type discriminator that is always `chatkit.thread.deleted`. - The execution context that produced this tool call. + - `"chatkit.thread.deleted"` - - `Direct object { type }` +### Example - - `type: "direct"` +```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" +``` - The caller type. Always `direct`. +#### Response - - `"direct"` +```json +{ + "id": "id", + "deleted": true, + "object": "chatkit.thread.deleted" +} +``` - - `Program object { caller_id, type }` +## List ChatKit threads - - `caller_id: string` +**get** `/chatkit/threads` - The call ID of the program item that produced this tool call. +List ChatKit threads with optional pagination and user filters. - - `type: "program"` +### Query Parameters - The caller type. Always `program`. +- `after: optional string` - - `"program"` + List items created after this thread item ID. Defaults to null for the first page. - - `output: optional string` +- `before: optional string` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + List items created before this thread item ID. Defaults to null for the newest results. - - `McpListTools object { id, server_label, tools, 3 more }` +- `limit: optional number` - A list of tools available on an MCP server. + Maximum number of thread items to return. Defaults to 20. - - `id: string` +- `order: optional "asc" or "desc"` - The unique ID of the list. + Sort order for results by creation time. Defaults to `desc`. - - `server_label: string` + - `"asc"` - The label of the MCP server. + - `"desc"` - - `tools: array of object { input_schema, name, annotations, description }` +- `user: optional string` - The tools available on the server. + Filter threads that belong to this user identifier. Defaults to null to return all users. - - `input_schema: unknown` +### Returns - The JSON schema describing the tool's input. +- `data: array of ChatKitThread` - - `name: string` + A list of items - The name of the tool. + - `id: string` - - `annotations: optional unknown` + Identifier of the thread. - Additional annotations about the tool. + - `created_at: number` - - `description: optional string` + Unix timestamp (in seconds) for when the thread was created. - The description of the tool. + - `object: "chatkit.thread"` - - `type: "mcp_list_tools"` + Type discriminator that is always `chatkit.thread`. - The type of the item. Always `mcp_list_tools`. + - `"chatkit.thread"` - - `"mcp_list_tools"` + - `status: object { type } or object { reason, type } or object { reason, type }` - - `agent: optional object { agent_name }` + Current status for the thread. Defaults to `active` for newly created threads. - The agent that produced this item. + - `Active object { type }` - - `agent_name: string` + Indicates that a thread is active. - The canonical name of the agent that produced this item. + - `type: "active"` - - `error: optional string` + Status discriminator that is always `active`. - Error message if the server could not list tools. + - `"active"` - - `McpApprovalRequest object { id, arguments, name, 3 more }` + - `Locked object { reason, type }` - A request for human approval of a tool invocation. + Indicates that a thread is locked and cannot accept new input. - - `id: string` + - `reason: string` - The unique ID of the approval request. + Reason that the thread was locked. Defaults to null when no reason is recorded. - - `arguments: string` + - `type: "locked"` - A JSON string of arguments for the tool. + Status discriminator that is always `locked`. - - `name: string` + - `"locked"` - The name of the tool to run. + - `Closed object { reason, type }` - - `server_label: string` + Indicates that a thread has been closed. - The label of the MCP server making the request. + - `reason: string` - - `type: "mcp_approval_request"` + Reason that the thread was closed. Defaults to null when no reason is recorded. - The type of the item. Always `mcp_approval_request`. + - `type: "closed"` - - `"mcp_approval_request"` + Status discriminator that is always `closed`. - - `agent: optional object { agent_name }` + - `"closed"` - The agent that produced this item. + - `title: string` - - `agent_name: string` + Optional human-readable title for the thread. Defaults to null when no title has been generated. - The canonical name of the agent that produced this item. + - `user: string` - - `McpApprovalResponse object { approval_request_id, approve, type, 3 more }` + Free-form string that identifies your end user who owns the thread. - A response to an MCP approval request. +- `first_id: string` - - `approval_request_id: string` + The ID of the first item in the list. - The ID of the approval request being answered. +- `has_more: boolean` - - `approve: boolean` + Whether there are more items available. - Whether the request was approved. +- `last_id: string` - - `type: "mcp_approval_response"` + The ID of the last item in the list. - The type of the item. Always `mcp_approval_response`. +- `object: "list"` - - `"mcp_approval_response"` + The type of object returned, must be `list`. - - `id: optional string` + - `"list"` - The unique ID of the approval response +### Example - - `agent: optional object { agent_name }` +```http +curl https://api.openai.com/v1/chatkit/threads \ + -H 'OpenAI-Beta: chatkit_beta=v1' \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - The agent that produced this item. +#### Response - - `agent_name: string` +```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" +} +``` - The canonical name of the agent that produced this item. +### Example - - `reason: optional string` +```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" +``` - Optional reason for the decision. +#### Response - - `McpCall object { id, arguments, name, 7 more }` +```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" +} +``` - An invocation of a tool on an MCP server. +## Domain Types - - `id: string` +### Chat Session - The unique ID of the tool call. +- `ChatSession object { id, chatkit_configuration, client_secret, 7 more }` - - `arguments: string` + Represents a ChatKit session and its resolved configuration. - A JSON string of the arguments passed to the tool. + - `id: string` - - `name: string` + Identifier for the ChatKit session. - The name of the tool that was run. + - `chatkit_configuration: ChatSessionChatKitConfiguration` - - `server_label: string` + Resolved ChatKit feature configuration for the session. - The label of the MCP server running the tool. + - `automatic_thread_titling: ChatSessionAutomaticThreadTitling` - - `type: "mcp_call"` + Automatic thread titling preferences. - The type of the item. Always `mcp_call`. + - `enabled: boolean` - - `"mcp_call"` + Whether automatic thread titling is enabled. - - `agent: optional object { agent_name }` + - `file_upload: ChatSessionFileUpload` - The agent that produced this item. + Upload settings for the session. - - `agent_name: string` + - `enabled: boolean` - The canonical name of the agent that produced this item. + Indicates if uploads are enabled for the session. - - `approval_request_id: optional string` + - `max_file_size: 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 upload size in megabytes. - - `error: optional string` + - `max_files: number` - The error from the tool call, if any. + Maximum number of uploads allowed during the session. - - `output: optional string` + - `history: ChatSessionHistory` - The output from the tool call. + History retention configuration. - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `enabled: boolean` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + Indicates if chat history is persisted for the session. - - `"in_progress"` + - `recent_threads: number` - - `"completed"` + Number of prior threads surfaced in history views. Defaults to null when all history is retained. - - `"incomplete"` + - `client_secret: string` - - `"calling"` + Ephemeral client secret that authenticates session requests. - - `"failed"` + - `expires_at: number` - - `CustomToolCallOutput object { call_id, output, type, 3 more }` + Unix timestamp (in seconds) for when the session expires. - The output of a custom tool call from your code, being sent back to the model. + - `max_requests_per_1_minute: number` - - `call_id: string` + Convenience copy of the per-minute request limit. - The call ID, used to map this custom tool call output to a custom tool call. + - `object: "chatkit.session"` - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + Type discriminator that is always `chatkit.session`. - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `"chatkit.session"` - - `StringOutput = string` + - `rate_limits: ChatSessionRateLimits` - A string of the output of the custom tool call. + Resolved rate limit values. - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `max_requests_per_1_minute: number` - Text, image, or file output of the custom tool call. + Maximum allowed requests per one-minute window. - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `status: ChatSessionStatus` - A text input to the model. + Current lifecycle state of the session. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `"active"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `"expired"` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `"cancelled"` - A file input to the model. + - `user: string` - - `type: "custom_tool_call_output"` + User identifier associated with the session. - The type of the custom tool call output. Always `custom_tool_call_output`. + - `workflow: ChatKitWorkflow` - - `"custom_tool_call_output"` + Workflow metadata for the session. - - `id: optional string` + - `id: string` - The unique ID of the custom tool call output in the OpenAI platform. + Identifier of the workflow backing the session. - - `agent: optional object { agent_name }` + - `state_variables: map[string or boolean or number]` - The agent that produced this item. + State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided. - - `agent_name: string` + - `string` - The canonical name of the agent that produced this item. + - `boolean` - - `caller: optional object { type } or object { caller_id, type }` + - `number` - The execution context that produced this tool call. + - `tracing: object { enabled }` - - `Direct object { type }` + Tracing settings applied to the workflow. - - `type: "direct"` + - `enabled: boolean` - The caller type. Always `direct`. + Indicates whether tracing is enabled. - - `"direct"` + - `version: string` - - `Program object { caller_id, type }` + Specific workflow version used for the session. Defaults to null when using the latest deployment. - - `caller_id: string` +### Chat Session Automatic Thread Titling - The call ID of the program item that produced this tool call. +- `ChatSessionAutomaticThreadTitling object { enabled }` - - `type: "program"` + Automatic thread title preferences for the session. - The caller type. Always `program`. + - `enabled: boolean` - - `"program"` + Whether automatic thread titling is enabled. - - `CustomToolCall object { call_id, input, name, 5 more }` +### Chat Session ChatKit Configuration - A call to a custom tool created by the model. +- `ChatSessionChatKitConfiguration object { automatic_thread_titling, file_upload, history }` - - `call_id: string` + ChatKit configuration for the session. - An identifier used to map this custom tool call to a tool call output. + - `automatic_thread_titling: ChatSessionAutomaticThreadTitling` - - `input: string` + Automatic thread titling preferences. - The input for the custom tool call generated by the model. + - `enabled: boolean` - - `name: string` + Whether automatic thread titling is enabled. - The name of the custom tool being called. + - `file_upload: ChatSessionFileUpload` - - `type: "custom_tool_call"` + Upload settings for the session. - The type of the custom tool call. Always `custom_tool_call`. + - `enabled: boolean` - - `"custom_tool_call"` + Indicates if uploads are enabled for the session. - - `id: optional string` + - `max_file_size: number` - The unique ID of the custom tool call in the OpenAI platform. + Maximum upload size in megabytes. - - `agent: optional object { agent_name }` + - `max_files: number` - The agent that produced this item. + Maximum number of uploads allowed during the session. - - `agent_name: string` + - `history: ChatSessionHistory` - The canonical name of the agent that produced this item. + History retention configuration. - - `caller: optional object { type } or object { caller_id, type }` + - `enabled: boolean` - The execution context that produced this tool call. + Indicates if chat history is persisted for the session. - - `Direct object { type }` + - `recent_threads: number` - - `type: "direct"` + Number of prior threads surfaced in history views. Defaults to null when all history is retained. - - `"direct"` +### Chat Session ChatKit Configuration Param - - `Program object { caller_id, type }` +- `ChatSessionChatKitConfigurationParam object { automatic_thread_titling, file_upload, history }` - - `caller_id: string` + Optional per-session configuration settings for ChatKit behavior. - The call ID of the program item that produced this tool call. + - `automatic_thread_titling: optional object { enabled }` - - `type: "program"` + Configuration for automatic thread titling. When omitted, automatic thread titling is enabled by default. - - `"program"` + - `enabled: optional boolean` - - `namespace: optional string` + Enable automatic thread title generation. Defaults to true. - The namespace of the custom tool being called. + - `file_upload: optional object { enabled, max_file_size, max_files }` - - `CompactionTrigger object { type, agent }` + Configuration for upload enablement and limits. When omitted, uploads are disabled by default (max_files 10, max_file_size 512 MB). - Compacts the current context. Must be the final input item. + - `enabled: optional boolean` - - `type: "compaction_trigger"` + Enable uploads for this session. Defaults to false. - The type of the item. Always `compaction_trigger`. + - `max_file_size: optional number` - - `"compaction_trigger"` + Maximum size in megabytes for each uploaded file. Defaults to 512 MB, which is the maximum allowable size. - - `agent: optional object { agent_name }` + - `max_files: optional number` - The agent that produced this item. + Maximum number of files that can be uploaded to the session. Defaults to 10. - - `agent_name: string` + - `history: optional object { enabled, recent_threads }` - The canonical name of the agent that produced this item. + Configuration for chat history retention. When omitted, history is enabled by default with no limit on recent_threads (null). - - `ItemReference object { id, agent, type }` + - `enabled: optional boolean` - An internal identifier for an item to reference. + Enables chat users to access previous ChatKit threads. Defaults to true. - - `id: string` + - `recent_threads: optional number` - The ID of the item to reference. + Number of recent ChatKit threads users have access to. Defaults to unlimited when unset. - - `agent: optional object { agent_name }` +### Chat Session Expires After Param - The agent that produced this item. +- `ChatSessionExpiresAfterParam object { anchor, seconds }` - - `agent_name: string` + Controls when the session expires relative to an anchor timestamp. - The canonical name of the agent that produced this item. + - `anchor: "created_at"` - - `type: optional "item_reference"` + Base timestamp used to calculate expiration. Currently fixed to `created_at`. - The type of item to reference. Always `item_reference`. + - `"created_at"` - - `"item_reference"` + - `seconds: number` - - `Program object { id, call_id, code, 3 more }` + Number of seconds after the anchor when the session expires. - - `id: string` +### Chat Session File Upload - The unique ID of this program item. +- `ChatSessionFileUpload object { enabled, max_file_size, max_files }` - - `call_id: string` + Upload permissions and limits applied to the session. - The stable call ID of the program item. + - `enabled: boolean` - - `code: string` + Indicates if uploads are enabled for the session. - The JavaScript source executed by programmatic tool calling. + - `max_file_size: number` - - `fingerprint: string` + Maximum upload size in megabytes. - Opaque program replay fingerprint that must be round-tripped. + - `max_files: number` - - `type: "program"` + Maximum number of uploads allowed during the session. - The item type. Always `program`. +### Chat Session History - - `"program"` +- `ChatSessionHistory object { enabled, recent_threads }` - - `agent: optional object { agent_name }` + History retention preferences returned for the session. - The agent that produced this item. + - `enabled: boolean` - - `agent_name: string` + Indicates if chat history is persisted for the session. - The canonical name of the agent that produced this item. + - `recent_threads: number` - - `ProgramOutput object { id, call_id, result, 3 more }` + Number of prior threads surfaced in history views. Defaults to null when all history is retained. - - `id: string` +### Chat Session Rate Limits - The unique ID of this program output item. +- `ChatSessionRateLimits object { max_requests_per_1_minute }` - - `call_id: string` + Active per-minute request limit for the session. - The call ID of the program item. + - `max_requests_per_1_minute: number` - - `result: string` + Maximum allowed requests per one-minute window. - The result produced by the program item. +### Chat Session Rate Limits Param - - `status: "completed" or "incomplete"` +- `ChatSessionRateLimitsParam object { max_requests_per_1_minute }` - The terminal status of the program output. + Controls request rate limits for the session. - - `"completed"` + - `max_requests_per_1_minute: optional number` - - `"incomplete"` + Maximum number of requests allowed per minute for the session. Defaults to 10. - - `type: "program_output"` +### Chat Session Status - The item type. Always `program_output`. +- `ChatSessionStatus = "active" or "expired" or "cancelled"` - - `"program_output"` + - `"active"` - - `agent: optional object { agent_name }` + - `"expired"` - The agent that produced this item. + - `"cancelled"` - - `agent_name: string` +### Chat Session Workflow Param - The canonical name of the agent that produced this item. +- `ChatSessionWorkflowParam object { id, state_variables, tracing, version }` - - `response_id: string` + Workflow reference and overrides applied to the chat session. - The ID of the response that rejected the input. + - `id: string` - - `sequence_number: number` + Identifier for the workflow invoked by the session. - The sequence number for this event. + - `state_variables: optional map[string or boolean or number]` - - `type: "response.inject.failed"` + 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. - The event discriminator. Always `response.inject.failed`. + - `string` - - `"response.inject.failed"` + - `boolean` - - `stream_id: optional string` + - `number` - The multiplexed WebSocket stream that emitted the event. This field is - present only when WebSocket multiplexing is enabled separately. + - `tracing: optional object { enabled }` -### Beta Skill Reference + Optional tracing overrides for the workflow invocation. When omitted, tracing is enabled by default. -- `BetaSkillReference object { skill_id, type, version }` + - `enabled: optional boolean` - - `skill_id: string` + Whether tracing is enabled during the session. Defaults to true. - The ID of the referenced skill. + - `version: optional string` - - `type: "skill_reference"` + Specific workflow version to run. Defaults to the latest deployed version. - References a skill created with the /v1/skills endpoint. +### ChatKit Attachment - - `"skill_reference"` +- `ChatKitAttachment object { id, mime_type, name, 2 more }` - - `version: optional string` + Attachment metadata included on thread items. - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `id: string` -### Beta Tool Choice Allowed + Identifier for the attachment. -- `BetaToolChoiceAllowed object { mode, tools, type }` + - `mime_type: string` - Constrains the tools available to the model to a pre-defined set. + MIME type of the attachment. - - `mode: "auto" or "required"` + - `name: string` - Constrains the tools available to the model to a pre-defined set. + Original display name for the attachment. - `auto` allows the model to pick from among the allowed tools and generate a - message. + - `preview_url: string` - `required` requires the model to call one or more of the allowed tools. + Preview URL for rendering the attachment inline. - - `"auto"` + - `type: "image" or "file"` - - `"required"` + Attachment discriminator. - - `tools: array of map[unknown]` + - `"image"` - A list of tool definitions that the model should be allowed to call. + - `"file"` - For the Responses API, the list of tool definitions might look like: +### ChatKit Response Output Text - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` +- `ChatKitResponseOutputText object { annotations, text, type }` - - `type: "allowed_tools"` + Assistant response text accompanied by optional annotations. - Allowed tool configuration type. Always `allowed_tools`. + - `annotations: array of object { source, type } or object { source, type }` - - `"allowed_tools"` + Ordered list of annotations attached to the response text. -### Beta Tool Choice Apply Patch + - `File object { source, type }` -- `BetaToolChoiceApplyPatch object { type }` + Annotation that references an uploaded file. - Forces the model to call the apply_patch tool when executing a tool call. + - `source: object { filename, type }` - - `type: "apply_patch"` + File attachment referenced by the annotation. - The tool to call. Always `apply_patch`. + - `filename: string` - - `"apply_patch"` + Filename referenced by the annotation. -### Beta Tool Choice Custom + - `type: "file"` -- `BetaToolChoiceCustom object { name, type }` + Type discriminator that is always `file`. - Use this option to force the model to call a specific custom tool. + - `"file"` - - `name: string` + - `type: "file"` - The name of the custom tool to call. + Type discriminator that is always `file` for this annotation. - - `type: "custom"` + - `"file"` - For custom tool calling, the type is always `custom`. + - `URL object { source, type }` - - `"custom"` + Annotation that references a URL. -### Beta Tool Choice Function + - `source: object { type, url }` -- `BetaToolChoiceFunction object { name, type }` + URL referenced by the annotation. - Use this option to force the model to call a specific function. + - `type: "url"` - - `name: string` + Type discriminator that is always `url`. - The name of the function to call. + - `"url"` - - `type: "function"` + - `url: string` - For function calling, the type is always `function`. + URL referenced by the annotation. - - `"function"` + - `type: "url"` -### Beta Tool Choice Mcp + Type discriminator that is always `url` for this annotation. -- `BetaToolChoiceMcp object { server_label, type, name }` + - `"url"` - Use this option to force the model to call a specific tool on a remote MCP server. + - `text: string` - - `server_label: string` + Assistant generated text. - The label of the MCP server to use. + - `type: "output_text"` - - `type: "mcp"` + Type discriminator that is always `output_text`. - For MCP tools, the type is always `mcp`. + - `"output_text"` - - `"mcp"` +### ChatKit Thread - - `name: optional string` +- `ChatKitThread object { id, created_at, object, 3 more }` - The name of the tool to call on the server. + Represents a ChatKit thread and its current status. -### Beta Tool Choice Options + - `id: string` -- `BetaToolChoiceOptions = "none" or "auto" or "required"` + Identifier of the thread. - Controls which (if any) tool is called by the model. + - `created_at: number` - `none` means the model will not call any tool and instead generates a message. + Unix timestamp (in seconds) for when the thread was created. - `auto` means the model can pick between generating a message or calling one or - more tools. + - `object: "chatkit.thread"` - `required` means the model must call one or more tools. + Type discriminator that is always `chatkit.thread`. - - `"none"` + - `"chatkit.thread"` - - `"auto"` + - `status: object { type } or object { reason, type } or object { reason, type }` - - `"required"` + Current status for the thread. Defaults to `active` for newly created threads. -### Beta Tool Choice Shell + - `Active object { type }` -- `BetaToolChoiceShell object { type }` + Indicates that a thread is active. - Forces the model to call the shell tool when a tool call is required. + - `type: "active"` - - `type: "shell"` + Status discriminator that is always `active`. - The tool to call. Always `shell`. + - `"active"` - - `"shell"` + - `Locked object { reason, type }` -### Beta Tool Choice Types + Indicates that a thread is locked and cannot accept new input. -- `BetaToolChoiceTypes object { type }` + - `reason: string` - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + Reason that the thread was locked. Defaults to null when no reason is recorded. - - `type: "file_search" or "web_search_preview" or "computer" or 5 more` + - `type: "locked"` - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + Status discriminator that is always `locked`. - Allowed values are: + - `"locked"` - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + - `Closed object { reason, type }` - - `"file_search"` + Indicates that a thread has been closed. - - `"web_search_preview"` + - `reason: string` - - `"computer"` + Reason that the thread was closed. Defaults to null when no reason is recorded. - - `"computer_use_preview"` + - `type: "closed"` - - `"computer_use"` + Status discriminator that is always `closed`. - - `"web_search_preview_2025_03_11"` + - `"closed"` - - `"image_generation"` + - `title: string` - - `"code_interpreter"` + Optional human-readable title for the thread. Defaults to null when no title has been generated. -# Input Items + - `user: string` -## List input items + Free-form string that identifies your end user who owns the thread. -**get** `/responses/{response_id}/input_items?beta=true` +### ChatKit Thread Assistant Message Item -List input items +- `ChatKitThreadAssistantMessageItem object { id, content, created_at, 3 more }` -### Path Parameters + Assistant-authored message within a thread. -- `response_id: string` + - `id: string` -### Query Parameters + Identifier of the thread item. -- `after: optional string` + - `content: array of ChatKitResponseOutputText` - An item ID to list items after, used in pagination. + Ordered assistant response segments. -- `include: optional array of BetaResponseIncludable` + - `annotations: array of object { source, type } or object { source, type }` - Additional fields to include in the response. See the `include` - parameter for Response creation above for more information. + Ordered list of annotations attached to the response text. - - `"file_search_call.results"` + - `File object { source, type }` - - `"web_search_call.results"` + Annotation that references an uploaded file. - - `"web_search_call.action.sources"` + - `source: object { filename, type }` - - `"message.input_image.image_url"` + File attachment referenced by the annotation. - - `"computer_call_output.output.image_url"` + - `filename: string` - - `"code_interpreter_call.outputs"` + Filename referenced by the annotation. - - `"reasoning.encrypted_content"` + - `type: "file"` - - `"message.output_text.logprobs"` + Type discriminator that is always `file`. -- `limit: optional number` + - `"file"` - A limit on the number of objects to be returned. Limit can range between - 1 and 100, and the default is 20. + - `type: "file"` -- `order: optional "asc" or "desc"` + Type discriminator that is always `file` for this annotation. - The order to return the input items in. Default is `desc`. + - `"file"` - - `asc`: Return the input items in ascending order. - - `desc`: Return the input items in descending order. + - `URL object { source, type }` - - `"asc"` + Annotation that references a URL. - - `"desc"` + - `source: object { type, url }` -### Header Parameters + URL referenced by the annotation. -- `"openai-beta": optional array of "responses_multi_agent=v1"` + - `type: "url"` - - `"responses_multi_agent=v1"` + Type discriminator that is always `url`. -### Returns + - `"url"` -- `BetaResponseItemList object { data, first_id, has_more, 2 more }` + - `url: string` - A list of Response items. + URL referenced by the annotation. - - `data: array of BetaResponseInputMessageItem or BetaResponseOutputMessage or object { id, queries, status, 3 more } or 29 more` + - `type: "url"` - A list of items used to generate this response. + Type discriminator that is always `url` for this annotation. - - `BetaResponseInputMessageItem object { id, content, role, 3 more }` + - `"url"` - - `id: string` + - `text: string` - The unique ID of the message input. + Assistant generated text. - - `content: BetaResponseInputMessageContentList` + - `type: "output_text"` - A list of one or many input items to the model, containing different content - types. + Type discriminator that is always `output_text`. - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `"output_text"` - A text input to the model. + - `created_at: number` - - `text: string` + Unix timestamp (in seconds) for when the item was created. - The text input to the model. + - `object: "chatkit.thread_item"` - - `type: "input_text"` + Type discriminator that is always `chatkit.thread_item`. - The type of the input item. Always `input_text`. + - `"chatkit.thread_item"` - - `"input_text"` + - `thread_id: string` - - `prompt_cache_breakpoint: optional object { mode }` + Identifier of the parent thread. - Marks the exact end of a reusable 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: "chatkit.assistant_message"` - - `mode: "explicit"` + Type discriminator that is always `chatkit.assistant_message`. - The breakpoint mode. Always `explicit`. + - `"chatkit.assistant_message"` - - `"explicit"` +### ChatKit Thread Item List - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` +- `ChatKitThreadItemList object { data, first_id, has_more, 2 more }` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + A paginated list of thread items rendered for the ChatKit API. - - `detail: "low" or "high" or "auto" or "original"` + - `data: array of ChatKitThreadUserMessageItem or ChatKitThreadAssistantMessageItem or ChatKitWidgetItem or 3 more` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + A list of items - - `"low"` + - `ChatKitThreadUserMessageItem object { id, attachments, content, 5 more }` - - `"high"` + User-authored messages within a thread. - - `"auto"` + - `id: string` - - `"original"` + Identifier of the thread item. - - `type: "input_image"` + - `attachments: array of ChatKitAttachment` - The type of the input item. Always `input_image`. + Attachments associated with the user message. Defaults to an empty list. - - `"input_image"` + - `id: string` - - `file_id: optional string` + Identifier for the attachment. - The ID of the file to be sent to the model. + - `mime_type: string` - - `image_url: optional string` + MIME type of the attachment. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `name: string` - - `prompt_cache_breakpoint: optional object { mode }` + Original display name for the attachment. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `preview_url: string` - - `mode: "explicit"` + Preview URL for rendering the attachment inline. - The breakpoint mode. Always `explicit`. + - `type: "image" or "file"` - - `"explicit"` + Attachment discriminator. - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `"image"` - A file input to the model. + - `"file"` - - `type: "input_file"` + - `content: array of object { text, type } or object { text, type }` - The type of the input item. Always `input_file`. + Ordered content elements supplied by the user. - - `"input_file"` + - `InputText object { text, type }` - - `detail: optional "auto" or "low" or "high"` + Text block that a user contributed to the thread. - 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`. + - `text: string` - - `"auto"` + Plain-text content supplied by the user. - - `"low"` + - `type: "input_text"` - - `"high"` + Type discriminator that is always `input_text`. - - `file_data: optional string` + - `"input_text"` - The content of the file to be sent to the model. + - `QuotedText object { text, type }` - - `file_id: optional string` + Quoted snippet that the user referenced in their message. - The ID of the file to be sent to the model. + - `text: string` - - `file_url: optional string` + Quoted text content. - The URL of the file to be sent to the model. + - `type: "quoted_text"` - - `filename: optional string` + Type discriminator that is always `quoted_text`. - The name of the file to be sent to the model. + - `"quoted_text"` - - `prompt_cache_breakpoint: optional object { mode }` + - `created_at: 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. + Unix timestamp (in seconds) for when the item was created. - - `mode: "explicit"` + - `inference_options: object { model, tool_choice }` - The breakpoint mode. Always `explicit`. + Inference overrides applied to the message. Defaults to null when unset. - - `"explicit"` + - `model: string` - - `role: "user" or "system" or "developer"` + Model name that generated the response. Defaults to null when using the session default. - The role of the message input. One of `user`, `system`, or `developer`. + - `tool_choice: object { id }` - - `"user"` + Preferred tool to invoke. Defaults to null when ChatKit should auto-select. - - `"system"` + - `id: string` - - `"developer"` + Identifier of the requested tool. - - `type: "message"` + - `object: "chatkit.thread_item"` - The type of the message input. Always set to `message`. + Type discriminator that is always `chatkit.thread_item`. - - `"message"` + - `"chatkit.thread_item"` - - `agent: optional object { agent_name }` + - `thread_id: string` - The agent that produced this item. + Identifier of the parent thread. - - `agent_name: string` + - `type: "chatkit.user_message"` - The canonical name of the agent that produced this item. + - `"chatkit.user_message"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `ChatKitThreadAssistantMessageItem object { id, content, created_at, 3 more }` - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Assistant-authored message within a thread. - - `"in_progress"` + - `id: string` - - `"completed"` + Identifier of the thread item. - - `"incomplete"` + - `content: array of ChatKitResponseOutputText` - - `BetaResponseOutputMessage object { id, content, role, 4 more }` + Ordered assistant response segments. - An output message from the model. + - `annotations: array of object { source, type } or object { source, type }` - - `id: string` + Ordered list of annotations attached to the response text. - The unique ID of the output message. + - `File object { source, type }` - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + Annotation that references an uploaded file. - The content of the output message. + - `source: object { filename, type }` - - `BetaResponseOutputText object { annotations, text, type, logprobs }` + File attachment referenced by the annotation. - A text output from the model. + - `filename: 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 }` + Filename referenced by the annotation. - The annotations of the text output. + - `type: "file"` - - `FileCitation object { file_id, filename, index, type }` + Type discriminator that is always `file`. - A citation to a file. + - `"file"` - - `file_id: string` + - `type: "file"` - The ID of the file. + Type discriminator that is always `file` for this annotation. - - `filename: string` + - `"file"` - The filename of the file cited. + - `URL object { source, type }` - - `index: number` + Annotation that references a URL. - The index of the file in the list of files. + - `source: object { type, url }` - - `type: "file_citation"` + URL referenced by the annotation. - The type of the file citation. Always `file_citation`. + - `type: "url"` - - `"file_citation"` + Type discriminator that is always `url`. - - `URLCitation object { end_index, start_index, title, 2 more }` + - `"url"` - A citation for a web resource used to generate a model response. + - `url: string` - - `end_index: number` + URL referenced by the annotation. - The index of the last character of the URL citation in the message. + - `type: "url"` - - `start_index: number` + Type discriminator that is always `url` for this annotation. - The index of the first character of the URL citation in the message. + - `"url"` - - `title: string` + - `text: string` - The title of the web resource. + Assistant generated text. - - `type: "url_citation"` + - `type: "output_text"` - The type of the URL citation. Always `url_citation`. + Type discriminator that is always `output_text`. - - `"url_citation"` + - `"output_text"` - - `url: string` + - `created_at: number` - The URL of the web resource. + Unix timestamp (in seconds) for when the item was created. - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + - `object: "chatkit.thread_item"` - A citation for a container file used to generate a model response. + Type discriminator that is always `chatkit.thread_item`. - - `container_id: string` + - `"chatkit.thread_item"` - The ID of the container file. + - `thread_id: string` - - `end_index: number` + Identifier of the parent thread. - The index of the last character of the container file citation in the message. + - `type: "chatkit.assistant_message"` - - `file_id: string` + Type discriminator that is always `chatkit.assistant_message`. - The ID of the file. + - `"chatkit.assistant_message"` - - `filename: string` + - `ChatKitWidgetItem object { id, created_at, object, 3 more }` - The filename of the container file cited. + Thread item that renders a widget payload. - - `start_index: number` + - `id: string` - The index of the first character of the container file citation in the message. + Identifier of the thread item. - - `type: "container_file_citation"` + - `created_at: number` - The type of the container file citation. Always `container_file_citation`. + Unix timestamp (in seconds) for when the item was created. - - `"container_file_citation"` + - `object: "chatkit.thread_item"` - - `FilePath object { file_id, index, type }` + Type discriminator that is always `chatkit.thread_item`. - A path to a file. + - `"chatkit.thread_item"` - - `file_id: string` + - `thread_id: string` - The ID of the file. + Identifier of the parent thread. - - `index: number` + - `type: "chatkit.widget"` - The index of the file in the list of files. + Type discriminator that is always `chatkit.widget`. - - `type: "file_path"` + - `"chatkit.widget"` - The type of the file path. Always `file_path`. + - `widget: string` - - `"file_path"` + Serialized widget payload rendered in the UI. - - `text: string` + - `ChatKitClientToolCall object { id, arguments, call_id, 7 more }` - The text output from the model. + Record of a client side tool invocation initiated by the assistant. - - `type: "output_text"` + - `id: string` - The type of the output text. Always `output_text`. + Identifier of the thread item. - - `"output_text"` + - `arguments: string` - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + JSON-encoded arguments that were sent to the tool. - - `token: string` + - `call_id: string` - - `bytes: array of number` + Identifier for the client tool call. - - `logprob: number` + - `created_at: number` - - `top_logprobs: array of object { token, bytes, logprob }` + Unix timestamp (in seconds) for when the item was created. - - `token: string` + - `name: string` - - `bytes: array of number` + Tool name that was invoked. - - `logprob: number` + - `object: "chatkit.thread_item"` - - `BetaResponseOutputRefusal object { refusal, type }` + Type discriminator that is always `chatkit.thread_item`. - A refusal from the model. + - `"chatkit.thread_item"` - - `refusal: string` + - `output: string` - The refusal explanation from the model. + JSON-encoded output captured from the tool. Defaults to null while execution is in progress. - - `type: "refusal"` + - `status: "in_progress" or "completed"` - The type of the refusal. Always `refusal`. + Execution status for the tool call. - - `"refusal"` + - `"in_progress"` - - `role: "assistant"` + - `"completed"` - The role of the output message. Always `assistant`. + - `thread_id: string` - - `"assistant"` + Identifier of the parent thread. - - `status: "in_progress" or "completed" or "incomplete"` + - `type: "chatkit.client_tool_call"` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + Type discriminator that is always `chatkit.client_tool_call`. - - `"in_progress"` + - `"chatkit.client_tool_call"` - - `"completed"` + - `ChatKitTask object { id, created_at, heading, 5 more }` - - `"incomplete"` + Task emitted by the workflow to show progress and status updates. - - `type: "message"` + - `id: string` - The type of the output message. Always `message`. + Identifier of the thread item. - - `"message"` + - `created_at: number` - - `agent: optional object { agent_name }` + Unix timestamp (in seconds) for when the item was created. - The agent that produced this item. + - `heading: string` - - `agent_name: string` + Optional heading for the task. Defaults to null when not provided. - The canonical name of the agent that produced this item. + - `object: "chatkit.thread_item"` - - `phase: optional "commentary" or "final_answer"` + Type discriminator that is always `chatkit.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. + - `"chatkit.thread_item"` - - `"commentary"` + - `summary: string` - - `"final_answer"` + Optional summary that describes the task. Defaults to null when omitted. - - `FileSearchCall object { id, queries, status, 3 more }` + - `task_type: "custom" or "thought"` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + Subtype for the task. - - `id: string` + - `"custom"` - The unique ID of the file search tool call. + - `"thought"` - - `queries: array of string` + - `thread_id: string` - The queries used to search for files. + Identifier of the parent thread. - - `status: "in_progress" or "searching" or "completed" or 2 more` + - `type: "chatkit.task"` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + Type discriminator that is always `chatkit.task`. - - `"in_progress"` + - `"chatkit.task"` - - `"searching"` + - `ChatKitTaskGroup object { id, created_at, object, 3 more }` - - `"completed"` + Collection of workflow tasks grouped together in the thread. - - `"incomplete"` + - `id: string` - - `"failed"` + Identifier of the thread item. - - `type: "file_search_call"` + - `created_at: number` - The type of the file search tool call. Always `file_search_call`. + Unix timestamp (in seconds) for when the item was created. - - `"file_search_call"` + - `object: "chatkit.thread_item"` - - `agent: optional object { agent_name }` + Type discriminator that is always `chatkit.thread_item`. - The agent that produced this item. + - `"chatkit.thread_item"` - - `agent_name: string` + - `tasks: array of object { heading, summary, type }` - The canonical name of the agent that produced this item. + Tasks included in the group. - - `results: optional array of object { attributes, file_id, filename, 2 more }` + - `heading: string` - The results of the file search tool call. + Optional heading for the grouped task. Defaults to null when not provided. - - `attributes: optional map[string or number or boolean]` + - `summary: 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. + Optional summary that describes the grouped task. Defaults to null when omitted. - - `string` + - `type: "custom" or "thought"` - - `number` + Subtype for the grouped task. - - `boolean` + - `"custom"` - - `file_id: optional string` + - `"thought"` - The unique ID of the file. + - `thread_id: string` - - `filename: optional string` + Identifier of the parent thread. - The name of the file. + - `type: "chatkit.task_group"` - - `score: optional number` + Type discriminator that is always `chatkit.task_group`. - The relevance score of the file - a value between 0 and 1. + - `"chatkit.task_group"` - - `text: optional string` + - `first_id: string` - The text that was retrieved from the file. + The ID of the first item in the list. - - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` + - `has_more: boolean` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + Whether there are more items available. - - `id: string` + - `last_id: string` - The unique ID of the computer call. + The ID of the last item in the list. - - `call_id: string` + - `object: "list"` - An identifier used when responding to the tool call with output. + The type of object returned, must be `list`. - - `pending_safety_checks: array of object { id, code, message }` + - `"list"` - The pending safety checks for the computer call. +### ChatKit Thread User Message Item - - `id: string` +- `ChatKitThreadUserMessageItem object { id, attachments, content, 5 more }` - The ID of the pending safety check. + User-authored messages within a thread. - - `code: optional string` + - `id: string` - The type of the pending safety check. + Identifier of the thread item. - - `message: optional string` + - `attachments: array of ChatKitAttachment` - Details about the pending safety check. + Attachments associated with the user message. Defaults to an empty list. - - `status: "in_progress" or "completed" or "incomplete"` + - `id: string` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Identifier for the attachment. - - `"in_progress"` + - `mime_type: string` - - `"completed"` + MIME type of the attachment. - - `"incomplete"` + - `name: string` - - `type: "computer_call"` + Original display name for the attachment. - The type of the computer call. Always `computer_call`. + - `preview_url: string` - - `"computer_call"` + Preview URL for rendering the attachment inline. - - `action: optional BetaComputerAction` + - `type: "image" or "file"` - A click action. + Attachment discriminator. - - `Click object { button, type, x, 2 more }` + - `"image"` - A click action. + - `"file"` - - `button: "left" or "right" or "wheel" or 2 more` + - `content: array of object { text, type } or object { text, type }` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + Ordered content elements supplied by the user. - - `"left"` + - `InputText object { text, type }` - - `"right"` + Text block that a user contributed to the thread. - - `"wheel"` + - `text: string` - - `"back"` + Plain-text content supplied by the user. - - `"forward"` + - `type: "input_text"` - - `type: "click"` + Type discriminator that is always `input_text`. - Specifies the event type. For a click action, this property is always `click`. + - `"input_text"` - - `"click"` + - `QuotedText object { text, type }` - - `x: number` + Quoted snippet that the user referenced in their message. - The x-coordinate where the click occurred. + - `text: string` - - `y: number` + Quoted text content. - The y-coordinate where the click occurred. + - `type: "quoted_text"` - - `keys: optional array of string` + Type discriminator that is always `quoted_text`. - The keys being held while clicking. + - `"quoted_text"` - - `DoubleClick object { keys, type, x, y }` + - `created_at: number` - A double click action. + Unix timestamp (in seconds) for when the item was created. - - `keys: array of string` + - `inference_options: object { model, tool_choice }` - The keys being held while double-clicking. + Inference overrides applied to the message. Defaults to null when unset. - - `type: "double_click"` + - `model: string` - Specifies the event type. For a double click action, this property is always set to `double_click`. + Model name that generated the response. Defaults to null when using the session default. - - `"double_click"` + - `tool_choice: object { id }` - - `x: number` + Preferred tool to invoke. Defaults to null when ChatKit should auto-select. - The x-coordinate where the double click occurred. + - `id: string` - - `y: number` + Identifier of the requested tool. - The y-coordinate where the double click occurred. + - `object: "chatkit.thread_item"` - - `Drag object { path, type, keys }` + Type discriminator that is always `chatkit.thread_item`. - A drag action. + - `"chatkit.thread_item"` - - `path: array of object { x, y }` + - `thread_id: string` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + Identifier of the parent thread. - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `type: "chatkit.user_message"` - - `x: number` + - `"chatkit.user_message"` - The x-coordinate. +### ChatKit Widget Item - - `y: number` +- `ChatKitWidgetItem object { id, created_at, object, 3 more }` - The y-coordinate. + Thread item that renders a widget payload. - - `type: "drag"` + - `id: string` - Specifies the event type. For a drag action, this property is always set to `drag`. + Identifier of the thread item. - - `"drag"` + - `created_at: number` - - `keys: optional array of string` + Unix timestamp (in seconds) for when the item was created. - The keys being held while dragging the mouse. + - `object: "chatkit.thread_item"` - - `Keypress object { keys, type }` + Type discriminator that is always `chatkit.thread_item`. - A collection of keypresses the model would like to perform. + - `"chatkit.thread_item"` - - `keys: array of string` + - `thread_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 parent thread. - - `type: "keypress"` + - `type: "chatkit.widget"` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + Type discriminator that is always `chatkit.widget`. - - `"keypress"` + - `"chatkit.widget"` - - `Move object { type, x, y, keys }` + - `widget: string` - A mouse move action. + Serialized widget payload rendered in the UI. - - `type: "move"` +### Thread Delete Response - Specifies the event type. For a move action, this property is always set to `move`. +- `ThreadDeleteResponse object { id, deleted, object }` - - `"move"` + Confirmation payload returned after deleting a thread. - - `x: number` + - `id: string` - The x-coordinate to move to. + Identifier of the deleted thread. - - `y: number` + - `deleted: boolean` - The y-coordinate to move to. + Indicates that the thread has been deleted. - - `keys: optional array of string` + - `object: "chatkit.thread.deleted"` - The keys being held while moving the mouse. + Type discriminator that is always `chatkit.thread.deleted`. - - `Screenshot object { type }` + - `"chatkit.thread.deleted"` - A screenshot action. +# Assistants - - `type: "screenshot"` +## List assistants - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. +**get** `/assistants` - - `"screenshot"` +Returns a list of assistants. - - `Scroll object { scroll_x, scroll_y, type, 3 more }` +### Query Parameters - A scroll action. +- `after: optional string` - - `scroll_x: number` + 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 horizontal scroll distance. +- `before: optional string` - - `scroll_y: number` + 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 vertical scroll distance. +- `limit: optional number` - - `type: "scroll"` + A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. - Specifies the event type. For a scroll action, this property is always set to `scroll`. +- `order: optional "asc" or "desc"` - - `"scroll"` + Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. - - `x: number` + - `"asc"` - The x-coordinate where the scroll occurred. + - `"desc"` - - `y: number` +### Returns - The y-coordinate where the scroll occurred. +- `data: array of Assistant` - - `keys: optional array of string` + - `id: string` - The keys being held while scrolling. + The identifier, which can be referenced in API endpoints. - - `Type object { text, type }` + - `created_at: number` - An action to type in text. + The Unix timestamp (in seconds) for when the assistant was created. - - `text: string` + - `description: string` - The text to type. + The description of the assistant. The maximum length is 512 characters. - - `type: "type"` + - `instructions: string` - Specifies the event type. For a type action, this property is always set to `type`. + The system instructions that the assistant uses. The maximum length is 256,000 characters. - - `"type"` + - `metadata: Metadata` - - `Wait 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. - A wait action. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `type: "wait"` + - `model: string` - Specifies the event type. For a wait action, this property is always set to `wait`. + 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. - - `"wait"` + - `name: string` - - `actions: optional BetaComputerActionList` + The name of the assistant. The maximum length is 256 characters. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `object: "assistant"` - - `Click object { button, type, x, 2 more }` + The object type, which is always `assistant`. - A click action. + - `"assistant"` - - `DoubleClick object { keys, type, x, y }` + - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool` - A double click action. + 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`. - - `Drag object { path, type, keys }` + - `CodeInterpreterTool object { type }` - A drag action. + - `type: "code_interpreter"` - - `Keypress object { keys, type }` + The type of tool being defined: `code_interpreter` - A collection of keypresses the model would like to perform. + - `"code_interpreter"` - - `Move object { type, x, y, keys }` + - `FileSearchTool object { type, file_search }` - A mouse move action. + - `type: "file_search"` - - `Screenshot object { type }` + The type of tool being defined: `file_search` - A screenshot action. + - `"file_search"` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `file_search: optional object { max_num_results, ranking_options }` - A scroll action. + Overrides for the file search tool. - - `Type object { text, type }` + - `max_num_results: optional number` - An action to type in 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. - - `Wait object { type }` + 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. - A wait action. + - `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. - - `ComputerCallOutput object { id, call_id, output, 5 more }` + - `ranker: optional "auto" or "default_2024_08_21"` - - `id: string` + The ranker to use for the file search. If not specified will use the `auto` ranker. - The unique ID of the computer call tool output. + - `"auto"` - - `call_id: string` + - `"default_2024_08_21"` - The ID of the computer tool call that produced the output. + - `FunctionTool object { function, type }` - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `function: FunctionDefinition` - A computer screenshot image used with the computer use tool. + - `name: string` - - `type: "computer_screenshot"` + 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. - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `description: optional string` - - `"computer_screenshot"` + A description of what the function does, used by the model to choose when and how to call the function. - - `file_id: optional string` + - `parameters: optional FunctionParameters` - The identifier of an uploaded file that contains the screenshot. + 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. - - `image_url: optional string` + Omitting `parameters` defines a function with an empty parameter list. - The URL of the screenshot image. + - `strict: optional boolean` - - `status: "completed" or "incomplete" or "failed" or "in_progress"` + 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 status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `type: "function"` - - `"completed"` + The type of tool being defined: `function` - - `"incomplete"` + - `"function"` - - `"failed"` + - `response_format: optional AssistantResponseFormatOption` - - `"in_progress"` + 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`. - - `type: "computer_call_output"` + 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 type of the computer tool call output. Always `computer_call_output`. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `"computer_call_output"` + **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. - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `"auto"` - The safety checks reported by the API that have been acknowledged by the - developer. + `auto` is the default value - - `id: string` + - `"auto"` - The ID of the pending safety check. + - `ResponseFormatText object { type }` - - `code: optional string` + Default response format. Used to generate text responses. - The type of the pending safety check. + - `type: "text"` - - `message: optional string` + The type of response format being defined. Always `text`. - Details about the pending safety check. + - `"text"` - - `agent: optional object { agent_name }` + - `ResponseFormatJSONObject object { type }` - The agent that produced this item. + 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_name: string` + - `type: "json_object"` - The canonical name of the agent that produced this item. + The type of response format being defined. Always `json_object`. - - `created_by: optional string` + - `"json_object"` - The identifier of the actor that created the item. + - `ResponseFormatJSONSchema object { json_schema, type }` - - `WebSearchCall object { id, action, status, 2 more }` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `json_schema: object { name, description, schema, strict }` - - `id: string` + Structured Outputs configuration options, including a JSON Schema. - The unique ID of the web search tool call. + - `name: string` - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + 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. - 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). + - `description: optional string` - - `Search object { type, queries, query, sources }` + A description of what the response format is for, used by the model to + determine how to respond in the format. - Action type "search" - Performs a web search query. + - `schema: optional map[unknown]` - - `type: "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 action type. + - `strict: optional boolean` - - `"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). - - `queries: optional array of string` + - `type: "json_schema"` - The search queries. + The type of response format being defined. Always `json_schema`. - - `query: optional string` + - `"json_schema"` - The search query. + - `temperature: optional number` - - `sources: optional array of object { type, url }` + 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 sources used in the search. + - `tool_resources: optional object { code_interpreter, file_search }` - - `type: "url"` + 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 type of source. Always `url`. + - `code_interpreter: optional object { file_ids }` - - `"url"` + - `file_ids: optional array of string` - - `url: 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. - The URL of the source. + - `file_search: optional object { vector_store_ids }` - - `OpenPage object { type, url }` + - `vector_store_ids: optional array of string` - Action type "open_page" - Opens a specific URL from search results. + 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. - - `type: "open_page"` + - `top_p: optional number` - The action type. + 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. - - `"open_page"` + We generally recommend altering this or temperature but not both. - - `url: optional string` +- `first_id: string` - The URL opened by the model. +- `has_more: boolean` - - `FindInPage object { pattern, type, url }` +- `last_id: string` - Action type "find_in_page": Searches for a pattern within a loaded page. +- `object: string` - - `pattern: string` +### Example - The pattern or text to search for within the page. +```http +curl https://api.openai.com/v1/assistants \ + -H 'OpenAI-Beta: assistants=v2' \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - - `type: "find_in_page"` +#### Response - The action type. +```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" +} +``` - - `"find_in_page"` +### Example - - `url: string` +```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" +``` - The URL of the page searched for the pattern. +#### Response - - `status: "in_progress" or "searching" or "completed" or "failed"` +```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 +} +``` - The status of the web search tool call. +## Create assistant - - `"in_progress"` +**post** `/assistants` - - `"searching"` +Create an assistant with a model and instructions. - - `"completed"` +### Body Parameters - - `"failed"` +- `model: string or "gpt-5" or "gpt-5-mini" or "gpt-5-nano" or 39 more` - - `type: "web_search_call"` + 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 web search tool call. Always `web_search_call`. + - `string` - - `"web_search_call"` + - `AssistantSupportedModels = "gpt-5" or "gpt-5-mini" or "gpt-5-nano" or 39 more` - - `agent: optional object { agent_name }` + 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 agent that produced this item. + - `"gpt-5"` - - `agent_name: string` + - `"gpt-5-mini"` - The canonical name of the agent that produced this item. + - `"gpt-5-nano"` - - `FunctionCall object { id, arguments, call_id, 7 more }` + - `"gpt-5-2025-08-07"` - - `id: string` + - `"gpt-5-mini-2025-08-07"` - The unique ID of the function tool call. + - `"gpt-5-nano-2025-08-07"` - - `arguments: string` + - `"gpt-4.1"` - A JSON string of the arguments to pass to the function. + - `"gpt-4.1-mini"` - - `call_id: string` + - `"gpt-4.1-nano"` - The unique ID of the function tool call generated by the model. + - `"gpt-4.1-2025-04-14"` - - `name: string` + - `"gpt-4.1-mini-2025-04-14"` - The name of the function to run. + - `"gpt-4.1-nano-2025-04-14"` - - `status: "in_progress" or "completed" or "incomplete"` + - `"o3-mini"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"o3-mini-2025-01-31"` - - `"in_progress"` + - `"o1"` - - `"completed"` + - `"o1-2024-12-17"` - - `"incomplete"` + - `"gpt-4o"` - - `type: "function_call"` + - `"gpt-4o-2024-11-20"` - The type of the function tool call. Always `function_call`. + - `"gpt-4o-2024-08-06"` - - `"function_call"` + - `"gpt-4o-2024-05-13"` - - `agent: optional object { agent_name }` + - `"gpt-4o-mini"` - The agent that produced this item. + - `"gpt-4o-mini-2024-07-18"` - - `agent_name: string` + - `"gpt-4.5-preview"` - The canonical name of the agent that produced this item. + - `"gpt-4.5-preview-2025-02-27"` - - `caller: optional object { type } or object { caller_id, type }` + - `"gpt-4-turbo"` - The execution context that produced this tool call. + - `"gpt-4-turbo-2024-04-09"` - - `Direct object { type }` + - `"gpt-4-0125-preview"` - - `type: "direct"` + - `"gpt-4-turbo-preview"` - - `"direct"` + - `"gpt-4-1106-preview"` - - `Program object { caller_id, type }` + - `"gpt-4-vision-preview"` - - `caller_id: string` + - `"gpt-4"` - The call ID of the program item that produced this tool call. + - `"gpt-4-0314"` - - `type: "program"` + - `"gpt-4-0613"` - - `"program"` + - `"gpt-4-32k"` - - `created_by: optional string` + - `"gpt-4-32k-0314"` - The identifier of the actor that created the item. + - `"gpt-4-32k-0613"` - - `namespace: optional string` + - `"gpt-3.5-turbo"` - The namespace of the function to run. + - `"gpt-3.5-turbo-16k"` - - `FunctionCallOutput object { id, call_id, output, 5 more }` + - `"gpt-3.5-turbo-0613"` - - `id: string` + - `"gpt-3.5-turbo-1106"` - The unique ID of the function call tool output. + - `"gpt-3.5-turbo-0125"` - - `call_id: string` + - `"gpt-3.5-turbo-16k-0613"` - The unique ID of the function tool call generated by the model. +- `description: optional string` - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + The description of the assistant. The maximum length is 512 characters. - The output from the function call generated by your code. - Can be a string or an list of output content. +- `instructions: optional string` - - `StringOutput = string` + The system instructions that the assistant uses. The maximum length is 256,000 characters. - A string of the output of the function call. +- `metadata: optional Metadata` - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + 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, image, or file output of the function call. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` +- `name: optional string` - A text input to the model. + The name of the assistant. The maximum length is 256 characters. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` +- `reasoning_effort: optional ReasoningEffort` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + 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. - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `"none"` - A file input to the model. + - `"minimal"` - - `status: "in_progress" or "completed" or "incomplete"` + - `"low"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"medium"` - - `"in_progress"` + - `"high"` - - `"completed"` + - `"xhigh"` - - `"incomplete"` + - `"max"` - - `type: "function_call_output"` +- `response_format: optional AssistantResponseFormatOption` - The type of the function tool call output. Always `function_call_output`. + 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`. - - `"function_call_output"` + 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"` - The caller type. Always `direct`. + The type of response format being defined. Always `text`. - - `"direct"` + - `"text"` - - `Program object { caller_id, type }` + - `ResponseFormatJSONObject object { type }` - - `caller_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. - The call ID of the program item that produced this tool call. + - `type: "json_object"` - - `type: "program"` + The type of response format being defined. Always `json_object`. - The caller type. Always `program`. + - `"json_object"` - - `"program"` + - `ResponseFormatJSONSchema object { json_schema, type }` - - `created_by: optional string` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - The identifier of the actor that created the item. + - `json_schema: object { name, description, schema, strict }` - - `AgentMessage object { id, author, content, 3 more }` + Structured Outputs configuration options, including a JSON Schema. - - `id: string` + - `name: string` - The unique ID of the agent 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. - - `author: string` + - `description: optional string` - The sending agent identity. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` + - `schema: optional map[unknown]` - Encrypted content sent between agents. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `strict: optional boolean` - A text input to the model. + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](/docs/guides/structured-outputs). - - `BetaResponseOutputText object { annotations, text, type, logprobs }` + - `type: "json_schema"` - A text output from the model. + The type of response format being defined. Always `json_schema`. - - `Text object { text, type }` + - `"json_schema"` - A text content. +- `temperature: optional number` - - `text: 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. - - `type: "text"` +- `tool_resources: optional object { code_interpreter, file_search }` - - `"text"` + 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. - - `SummaryText object { text, type }` + - `code_interpreter: optional object { file_ids }` - A summary text from the model. + - `file_ids: optional array of string` - - `text: 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. - A summary of the reasoning output from the model so far. + - `file_search: optional object { vector_store_ids, vector_stores }` - - `type: "summary_text"` + - `vector_store_ids: optional array of string` - The type of the object. Always `summary_text`. + 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. - - `"summary_text"` + - `vector_stores: optional array of object { chunking_strategy, file_ids, metadata }` - - `ReasoningText object { text, type }` + 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. - Reasoning text from the model. + - `chunking_strategy: optional object { type } or object { static, type }` - - `text: string` + The chunking strategy used to chunk the file(s). If not set, will use the `auto` strategy. - The reasoning text from the model. + - `AutoChunkingStrategy object { type }` - - `type: "reasoning_text"` + The default strategy. This strategy currently uses a `max_chunk_size_tokens` of `800` and `chunk_overlap_tokens` of `400`. - The type of the reasoning text. Always `reasoning_text`. + - `type: "auto"` - - `"reasoning_text"` + Always `auto`. - - `BetaResponseOutputRefusal object { refusal, type }` + - `"auto"` - A refusal from the model. + - `StaticChunkingStrategy object { static, type }` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `static: object { chunk_overlap_tokens, max_chunk_size_tokens }` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `chunk_overlap_tokens: number` - - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` + The number of tokens that overlap between chunks. The default value is `400`. - A screenshot of a computer. + Note that the overlap must not exceed half of `max_chunk_size_tokens`. - - `detail: "low" or "high" or "auto" or "original"` + - `max_chunk_size_tokens: 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 maximum number of tokens in each chunk. The default value is `800`. The minimum value is `100` and the maximum value is `4096`. - - `"low"` + - `type: "static"` - - `"high"` + Always `static`. - - `"auto"` + - `"static"` - - `"original"` + - `file_ids: optional array of string` - - `file_id: 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 identifier of an uploaded file that contains the screenshot. + - `metadata: optional Metadata` - - `image_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. - The URL of the screenshot image. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `type: "computer_screenshot"` +- `tools: optional array of CodeInterpreterTool or FileSearchTool or FunctionTool` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + 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`. - - `"computer_screenshot"` + - `CodeInterpreterTool object { type }` - - `prompt_cache_breakpoint: optional object { mode }` + - `type: "code_interpreter"` - Marks the exact end of a reusable 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 tool being defined: `code_interpreter` - - `mode: "explicit"` + - `"code_interpreter"` - The breakpoint mode. Always `explicit`. + - `FileSearchTool object { type, file_search }` - - `"explicit"` + - `type: "file_search"` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + The type of tool being defined: `file_search` - A file input to the model. + - `"file_search"` - - `EncryptedContent object { encrypted_content, type }` + - `file_search: optional object { max_num_results, ranking_options }` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + Overrides for the file search tool. - - `encrypted_content: string` + - `max_num_results: optional number` - Opaque encrypted content. + 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: "encrypted_content"` + 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 the input item. Always `encrypted_content`. + - `ranking_options: optional object { score_threshold, ranker }` - - `"encrypted_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. - - `recipient: string` + See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - The destination agent identity. + - `score_threshold: number` - - `type: "agent_message"` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - The type of the item. Always `agent_message`. + - `ranker: optional "auto" or "default_2024_08_21"` - - `"agent_message"` + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `agent: optional object { agent_name }` + - `"auto"` - The agent that produced this item. + - `"default_2024_08_21"` - - `agent_name: string` + - `FunctionTool object { function, type }` - The canonical name of the agent that produced this item. + - `function: FunctionDefinition` - - `MultiAgentCall object { id, action, arguments, 3 more }` + - `name: string` - - `id: 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 the multi-agent call item. + - `description: optional string` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + A description of what the function does, used by the model to choose when and how to call the function. - The multi-agent action to execute. + - `parameters: optional FunctionParameters` - - `"spawn_agent"` + 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. - - `"interrupt_agent"` + Omitting `parameters` defines a function with an empty parameter list. - - `"list_agents"` + - `strict: optional boolean` - - `"send_message"` + 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). - - `"followup_task"` + - `type: "function"` - - `"wait_agent"` + The type of tool being defined: `function` - - `arguments: string` + - `"function"` - The JSON string of arguments generated for the action. +- `top_p: optional 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 linking this call to its output. + We generally recommend altering this or temperature but not both. - - `type: "multi_agent_call"` +### Returns - The type of the multi-agent call. Always `multi_agent_call`. +- `Assistant object { id, created_at, description, 10 more }` - - `"multi_agent_call"` + Represents an `assistant` that can call the model and use tools. - - `agent: optional object { agent_name }` + - `id: string` - The agent that produced this item. + The identifier, which can be referenced in API endpoints. - - `agent_name: string` + - `created_at: number` - The canonical name of the agent that produced this item. + The Unix timestamp (in seconds) for when the assistant was created. - - `MultiAgentCallOutput object { id, action, call_id, 3 more }` + - `description: string` - - `id: string` + The description of the assistant. The maximum length is 512 characters. - The unique ID of the multi-agent call output item. + - `instructions: string` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + The system instructions that the assistant uses. The maximum length is 256,000 characters. - The multi-agent action that produced this result. + - `metadata: Metadata` - - `"spawn_agent"` + 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. - - `"interrupt_agent"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `"list_agents"` + - `model: string` - - `"send_message"` + 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. - - `"followup_task"` + - `name: string` - - `"wait_agent"` + The name of the assistant. The maximum length is 256 characters. - - `call_id: string` + - `object: "assistant"` - The unique ID of the multi-agent call. + The object type, which is always `assistant`. - - `output: array of BetaResponseOutputText` + - `"assistant"` - Text output returned by the multi-agent action. + - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool` - - `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 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 annotations of the text output. + - `CodeInterpreterTool object { type }` - - `text: string` + - `type: "code_interpreter"` - The text output from the model. + The type of tool being defined: `code_interpreter` - - `type: "output_text"` + - `"code_interpreter"` - The type of the output text. Always `output_text`. + - `FileSearchTool object { type, file_search }` - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + - `type: "file_search"` - - `type: "multi_agent_call_output"` + The type of tool being defined: `file_search` - The type of the multi-agent result. Always `multi_agent_call_output`. + - `"file_search"` - - `"multi_agent_call_output"` + - `file_search: optional object { max_num_results, ranking_options }` - - `agent: optional object { agent_name }` + Overrides for the file search tool. - The agent that produced this item. + - `max_num_results: optional number` - - `agent_name: 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 canonical name of the agent that produced this item. + 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. - - `ToolSearchCall object { id, arguments, call_id, 5 more }` + - `ranking_options: optional object { score_threshold, ranker }` - - `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 unique ID of the tool search call item. + See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `arguments: unknown` + - `score_threshold: number` - Arguments used for the tool search call. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `call_id: 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: "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: "in_progress" or "completed" or "incomplete"` + - `name: string` - The status of the tool search call item that was recorded. + The name of the function to 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` - - `type: "tool_search_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 `tool_search_call`. + Omitting `parameters` defines a function with an empty parameter list. - - `"tool_search_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"` - - `created_by: optional string` + - `response_format: optional AssistantResponseFormatOption` - The identifier of the actor that created the item. + 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`. - - `ToolSearchOutput object { id, call_id, execution, 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). - - `id: string` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - The unique ID of the tool search output 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. - - `call_id: string` + - `"auto"` - The unique ID of the tool search call generated by the model. + `auto` is the default value - - `execution: "server" or "client"` + - `"auto"` - Whether tool search was executed by the server or by the client. + - `ResponseFormatText object { type }` - - `"server"` + Default response format. Used to generate text responses. - - `"client"` + - `type: "text"` - - `status: "in_progress" or "completed" or "incomplete"` + The type of response format being defined. Always `text`. - The status of the tool search output item that was recorded. + - `"text"` - - `"in_progress"` + - `ResponseFormatJSONObject object { type }` - - `"completed"` + 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. - - `"incomplete"` + - `type: "json_object"` - - `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 response format being defined. Always `json_object`. - The loaded tool definitions returned by tool search. + - `"json_object"` - - `Function object { name, parameters, strict, 5 more }` + - `ResponseFormatJSONSchema object { json_schema, 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). + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - - `name: string` + - `json_schema: object { name, description, schema, strict }` - The name of the function to call. + Structured Outputs configuration options, including a JSON Schema. - - `parameters: map[unknown]` + - `name: string` - A JSON schema object describing the parameters of the function. + 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. - - `strict: boolean` + - `description: optional string` - Whether strict parameter validation is enforced for this function tool. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `type: "function"` + - `schema: optional map[unknown]` - The type of the function tool. Always `function`. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `"function"` + - `strict: optional boolean` - - `allowed_callers: optional array of "direct" or "programmatic"` + 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 tool invocation context(s). + - `type: "json_schema"` - - `"direct"` + The type of response format being defined. Always `json_schema`. - - `"programmatic"` + - `"json_schema"` - - `defer_loading: optional boolean` + - `temperature: optional number` - Whether this function is deferred and loaded 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. - - `description: optional string` + - `tool_resources: optional object { code_interpreter, file_search }` - A description of the function. Used by the model to determine whether or not to call the function. + 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. - - `output_schema: optional map[unknown]` + - `code_interpreter: optional object { file_ids }` - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `file_ids: optional array of string` - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + 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. - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `file_search: optional object { vector_store_ids }` - - `type: "file_search"` + - `vector_store_ids: optional array of string` - The type of the file search tool. Always `file_search`. + 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. - - `"file_search"` + - `top_p: optional number` - - `vector_store_ids: 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. - The IDs of the vector stores to search. + We generally recommend altering this or temperature but not both. - - `filters: optional object { key, type, value } or object { filters, type }` +### Example - A filter to apply. +```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 + }' +``` - - `ComparisonFilter object { key, type, value }` +#### Response - A filter used to compare a specified attribute key to a given value using a defined comparison operation. +```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 +} +``` - - `key: string` +### Code Interpreter - The key to compare against the value. +```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" + }' +``` - - `type: "eq" or "ne" or "gt" or 5 more` +#### Response - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. +```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" +} +``` - - `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 +### Files - - `"eq"` +```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" + }' +``` - - `"ne"` +#### Response - - `"gt"` +```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" +} +``` - - `"gte"` +## Retrieve assistant - - `"lt"` +**get** `/assistants/{assistant_id}` - - `"lte"` +Retrieves an assistant. - - `"in"` +### Path Parameters - - `"nin"` +- `assistant_id: string` - - `value: string or number or boolean or array of string or number` +### Returns - The value to compare against the attribute key; supports string, number, or boolean types. +- `Assistant object { id, created_at, description, 10 more }` - - `string` + Represents an `assistant` that can call the model and use tools. - - `number` + - `id: string` - - `boolean` + The identifier, which can be referenced in API endpoints. - - `array of string or number` + - `created_at: number` - - `string` + The Unix timestamp (in seconds) for when the assistant was created. - - `number` + - `description: string` - - `CompoundFilter object { filters, type }` + The description of the assistant. The maximum length is 512 characters. - Combine multiple filters using `and` or `or`. + - `instructions: string` - - `filters: array of object { key, type, value } or unknown` + The system instructions that the assistant uses. The maximum length is 256,000 characters. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `metadata: Metadata` - - `ComparisonFilter object { key, type, 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. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `key: string` + - `model: string` - The key to compare against the value. + 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: "eq" or "ne" or "gt" or 5 more` + - `name: string` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The name of the assistant. The maximum length is 256 characters. - - `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: "assistant"` - - `"eq"` + The object type, which is always `assistant`. - - `"ne"` + - `"assistant"` - - `"gt"` + - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool` - - `"gte"` + 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`. - - `"lt"` + - `CodeInterpreterTool object { type }` - - `"lte"` + - `type: "code_interpreter"` - - `"in"` + The type of tool being defined: `code_interpreter` - - `"nin"` + - `"code_interpreter"` - - `value: string or number or boolean or array of string or number` + - `FileSearchTool object { type, file_search }` - The value to compare against the attribute key; supports string, number, or boolean types. + - `type: "file_search"` - - `string` + The type of tool being defined: `file_search` - - `number` + - `"file_search"` - - `boolean` + - `file_search: optional object { max_num_results, ranking_options }` - - `array of string or number` + Overrides for the file search tool. - - `string` + - `max_num_results: optional number` - - `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. - - `unknown` + 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: "and" or "or"` + - `ranking_options: optional object { score_threshold, ranker }` - Type of operation: `and` or `or`. + 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. - - `"and"` + See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `"or"` + - `score_threshold: number` - - `max_num_results: optional number` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `ranker: optional "auto" or "default_2024_08_21"` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + The ranker to use for the file search. If not specified will use the `auto` ranker. - Ranking options for search. + - `"auto"` - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `"default_2024_08_21"` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `FunctionTool object { function, type }` - - `embedding_weight: number` + - `function: FunctionDefinition` - The weight of the embedding in the reciprocal ranking fusion. + - `name: string` - - `text_weight: 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 weight of the text in the reciprocal ranking fusion. + - `description: optional string` - - `ranker: optional "auto" or "default-2024-11-15"` + A description of what the function does, used by the model to choose when and how to call the function. - The ranker to use for the file search. + - `parameters: optional FunctionParameters` - - `"auto"` + 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. - - `"default-2024-11-15"` + Omitting `parameters` defines a function with an empty parameter list. - - `score_threshold: optional number` + - `strict: optional boolean` - 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. + 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). - - `Computer object { type }` + - `type: "function"` - 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 tool being defined: `function` - - `type: "computer"` + - `"function"` - The type of the computer tool. Always `computer`. + - `response_format: optional AssistantResponseFormatOption` - - `"computer"` + 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`. - - `ComputerUsePreview object { display_height, display_width, environment, type }` + 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). - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `display_height: 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 height of the computer display. + - `"auto"` - - `display_width: number` + `auto` is the default value - The width of the computer display. + - `"auto"` - - `environment: "windows" or "mac" or "linux" or 2 more` + - `ResponseFormatText object { type }` - The type of computer environment to control. + Default response format. Used to generate text responses. - - `"windows"` + - `type: "text"` - - `"mac"` + The type of response format being defined. Always `text`. - - `"linux"` + - `"text"` - - `"ubuntu"` + - `ResponseFormatJSONObject object { type }` - - `"browser"` + 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: "computer_use_preview"` + - `type: "json_object"` - The type of the computer use tool. Always `computer_use_preview`. + The type of response format being defined. Always `json_object`. - - `"computer_use_preview"` + - `"json_object"` - - `WebSearch object { type, filters, search_context_size, user_location }` + - `ResponseFormatJSONSchema object { json_schema, type }` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - - `type: "web_search" or "web_search_2025_08_26"` + - `json_schema: object { name, description, schema, strict }` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + Structured Outputs configuration options, including a JSON Schema. - - `"web_search"` + - `name: string` - - `"web_search_2025_08_26"` + 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. - - `filters: optional object { allowed_domains }` + - `description: optional string` - Filters for the search. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `allowed_domains: optional array of string` + - `schema: optional map[unknown]` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `strict: optional boolean` - - `search_context_size: optional "low" or "medium" or "high"` + 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). - 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: "json_schema"` - - `"low"` + The type of response format being defined. Always `json_schema`. - - `"medium"` + - `"json_schema"` - - `"high"` + - `temperature: optional number` - - `user_location: optional object { city, country, region, 2 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. - The approximate location of the user. + - `tool_resources: optional object { code_interpreter, file_search }` - - `city: optional 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. - Free text input for the city of the user, e.g. `San Francisco`. + - `code_interpreter: optional object { file_ids }` - - `country: optional string` + - `file_ids: optional array of string` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + 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. - - `region: optional string` + - `file_search: optional object { vector_store_ids }` - Free text input for the region of the user, e.g. `California`. + - `vector_store_ids: optional array of string` - - `timezone: 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 [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `top_p: optional number` - - `type: optional "approximate"` + 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 location approximation. Always `approximate`. + We generally recommend altering this or temperature but not both. - - `"approximate"` +### Example - - `Mcp object { server_label, type, allowed_callers, 9 more }` +```http +curl https://api.openai.com/v1/assistants/$ASSISTANT_ID \ + -H 'OpenAI-Beta: assistants=v2' \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). +#### Response - - `server_label: string` +```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 +} +``` - A label for this MCP server, used to identify it in tool calls. +### Example - - `type: "mcp"` +```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 type of the MCP tool. Always `mcp`. +#### Response - - `"mcp"` +```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" +} +``` - - `allowed_callers: optional array of "direct" or "programmatic"` +## Modify assistant - The tool invocation context(s). +**post** `/assistants/{assistant_id}` - - `"direct"` +Modifies an assistant. - - `"programmatic"` +### Path Parameters - - `allowed_tools: optional array of string or object { read_only, tool_names }` +- `assistant_id: string` - List of allowed tool names or a filter object. +### Body Parameters - - `McpAllowedTools = array of string` +- `description: optional string` - A string array of allowed tool names + The description of the assistant. The maximum length is 512 characters. - - `McpToolFilter object { read_only, tool_names }` +- `instructions: optional string` - A filter object to specify which tools are allowed. + The system instructions that the assistant uses. The maximum length is 256,000 characters. - - `read_only: optional boolean` +- `metadata: optional Metadata` - 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. + 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. - - `tool_names: optional array of string` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - List of allowed tool names. +- `model: optional string or "gpt-5" or "gpt-5-mini" or "gpt-5-nano" or 39 more` - - `authorization: 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. - 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. + - `string` - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + - `AssistantSupportedModels = "gpt-5" or "gpt-5-mini" or "gpt-5-nano" or 39 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + 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. - Currently supported `connector_id` values are: + - `"gpt-5"` - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + - `"gpt-5-mini"` - - `"connector_dropbox"` + - `"gpt-5-nano"` - - `"connector_gmail"` + - `"gpt-5-2025-08-07"` - - `"connector_googlecalendar"` + - `"gpt-5-mini-2025-08-07"` - - `"connector_googledrive"` + - `"gpt-5-nano-2025-08-07"` - - `"connector_microsoftteams"` + - `"gpt-4.1"` - - `"connector_outlookcalendar"` + - `"gpt-4.1-mini"` - - `"connector_outlookemail"` + - `"gpt-4.1-nano"` - - `"connector_sharepoint"` + - `"gpt-4.1-2025-04-14"` - - `defer_loading: optional boolean` + - `"gpt-4.1-mini-2025-04-14"` - Whether this MCP tool is deferred and discovered via tool search. + - `"gpt-4.1-nano-2025-04-14"` - - `headers: optional map[string]` + - `"o3-mini"` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `"o3-mini-2025-01-31"` - - `require_approval: optional object { always, never } or "always" or "never"` + - `"o1"` - Specify which of the MCP server's tools require approval. + - `"o1-2024-12-17"` - - `McpToolApprovalFilter object { always, never }` + - `"gpt-4o"` - 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-2024-11-20"` - - `always: optional object { read_only, tool_names }` + - `"gpt-4o-2024-08-06"` - A filter object to specify which tools are allowed. + - `"gpt-4o-2024-05-13"` - - `read_only: optional boolean` + - `"gpt-4o-mini"` - 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-4o-mini-2024-07-18"` - - `tool_names: optional array of string` + - `"gpt-4.5-preview"` - List of allowed tool names. + - `"gpt-4.5-preview-2025-02-27"` - - `never: optional object { read_only, tool_names }` + - `"gpt-4-turbo"` - A filter object to specify which tools are allowed. + - `"gpt-4-turbo-2024-04-09"` - - `read_only: optional boolean` + - `"gpt-4-0125-preview"` - 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-turbo-preview"` - - `tool_names: optional array of string` + - `"gpt-4-1106-preview"` - List of allowed tool names. + - `"gpt-4-vision-preview"` - - `McpToolApprovalSetting = "always" or "never"` + - `"gpt-4"` - 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-0314"` - - `"always"` + - `"gpt-4-0613"` - - `"never"` + - `"gpt-4-32k"` - - `server_description: optional string` + - `"gpt-4-32k-0314"` - Optional description of the MCP server, used to provide more context. + - `"gpt-4-32k-0613"` - - `server_url: optional string` + - `"gpt-3.5-turbo"` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `"gpt-3.5-turbo-16k"` - - `tunnel_id: optional string` + - `"gpt-3.5-turbo-0613"` - 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-1106"` - - `CodeInterpreter object { container, type, allowed_callers }` + - `"gpt-3.5-turbo-0125"` - A tool that runs Python code to help generate a response to a prompt. + - `"gpt-3.5-turbo-16k-0613"` - - `container: string or object { type, file_ids, memory_limit, network_policy }` +- `name: 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 name of the assistant. The maximum length is 256 characters. - - `string` +- `reasoning_effort: optional ReasoningEffort` - The container ID. + 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. - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + - `"none"` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `"minimal"` - - `type: "auto"` + - `"low"` - Always `auto`. + - `"medium"` - - `"auto"` + - `"high"` - - `file_ids: optional array of string` + - `"xhigh"` - An optional list of uploaded files to make available to your code. + - `"max"` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` +- `response_format: optional AssistantResponseFormatOption` - The memory limit for the code interpreter container. + 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`. - - `"1g"` + 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). - - `"4g"` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `"16g"` + **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. - - `"64g"` + - `"auto"` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + `auto` is the default value - Network access policy for the container. + - `"auto"` - - `BetaContainerNetworkPolicyDisabled object { type }` + - `ResponseFormatText object { type }` - - `type: "disabled"` + Default response format. Used to generate text responses. - Disable outbound network access. Always `disabled`. + - `type: "text"` - - `"disabled"` + The type of response format being defined. Always `text`. - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `"text"` - - `allowed_domains: array of string` + - `ResponseFormatJSONObject object { type }` - A list of allowed domains when type is `allowlist`. + 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: "allowlist"` + - `type: "json_object"` - Allow outbound network access only to specified domains. Always `allowlist`. + The type of response format being defined. Always `json_object`. - - `"allowlist"` + - `"json_object"` - - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` + - `ResponseFormatJSONSchema object { json_schema, type }` - Optional domain-scoped secrets for allowlisted domains. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - - `domain: string` + - `json_schema: object { name, description, schema, strict }` - The domain associated with the secret. + Structured Outputs configuration options, including a JSON Schema. - `name: string` - The name of the secret to inject for the domain. + 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. - - `value: string` + - `description: optional string` - The secret value to inject for the domain. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `type: "code_interpreter"` + - `schema: optional map[unknown]` - The type of the code interpreter tool. Always `code_interpreter`. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `"code_interpreter"` + - `strict: optional boolean` - - `allowed_callers: optional array of "direct" or "programmatic"` + 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 tool invocation context(s). + - `type: "json_schema"` - - `"direct"` + The type of response format being defined. Always `json_schema`. - - `"programmatic"` + - `"json_schema"` - - `ProgrammaticToolCalling object { type }` +- `temperature: optional number` - - `type: "programmatic_tool_calling"` + 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 type of the tool. Always `programmatic_tool_calling`. +- `tool_resources: optional object { code_interpreter, file_search }` - - `"programmatic_tool_calling"` + 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. - - `ImageGeneration object { type, action, background, 9 more }` + - `code_interpreter: optional object { file_ids }` - A tool that generates images using the GPT image models. + - `file_ids: optional array of string` - - `type: "image_generation"` + 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. - The type of the image generation tool. Always `image_generation`. + - `file_search: optional object { vector_store_ids }` - - `"image_generation"` + - `vector_store_ids: optional array of string` - - `action: optional "generate" or "edit" or "auto"` + 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. - Whether to generate a new image or edit an existing image. Default: `auto`. +- `tools: optional array of CodeInterpreterTool or FileSearchTool or FunctionTool` - - `"generate"` + 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`. - - `"edit"` + - `CodeInterpreterTool object { type }` - - `"auto"` + - `type: "code_interpreter"` - - `background: optional "transparent" or "opaque" or "auto"` + The type of tool being defined: `code_interpreter` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + - `"code_interpreter"` - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + - `FileSearchTool object { type, file_search }` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `type: "file_search"` - - `"transparent"` + The type of tool being defined: `file_search` - - `"opaque"` + - `"file_search"` - - `"auto"` + - `file_search: optional object { max_num_results, ranking_options }` - - `input_fidelity: optional "high" or "low"` + Overrides for the file search 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`. + - `max_num_results: optional number` - - `"high"` + 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. - - `"low"` + 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_image_mask: optional object { file_id, image_url }` + - `ranking_options: optional object { score_threshold, ranker }` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + 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. - - `file_id: optional string` + See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - File ID for the mask image. + - `score_threshold: number` - - `image_url: optional string` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - Base64-encoded mask image. + - `ranker: optional "auto" or "default_2024_08_21"` - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + The ranker to use for the file search. If not specified will use the `auto` ranker. - The image generation model to use. Default: `gpt-image-1`. + - `"auto"` - - `string` + - `"default_2024_08_21"` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `FunctionTool object { function, type }` - The image generation model to use. Default: `gpt-image-1`. + - `function: FunctionDefinition` - - `"gpt-image-1"` + - `name: string` - - `"gpt-image-1-mini"` + 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-image-2"` + - `description: optional string` - - `"gpt-image-2-2026-04-21"` + A description of what the function does, used by the model to choose when and how to call the function. - - `"gpt-image-1.5"` + - `parameters: optional FunctionParameters` - - `"chatgpt-image-latest"` + 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. - - `moderation: optional "auto" or "low"` + Omitting `parameters` defines a function with an empty parameter list. - Moderation level for the generated image. Default: `auto`. + - `strict: optional boolean` - - `"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). - - `"low"` + - `type: "function"` - - `output_compression: optional number` + The type of tool being defined: `function` - Compression level for the output image. Default: 100. + - `"function"` - - `output_format: optional "png" or "webp" or "jpeg"` +- `top_p: optional number` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + 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. - - `"png"` + We generally recommend altering this or temperature but not both. - - `"webp"` +### Returns - - `"jpeg"` +- `Assistant object { id, created_at, description, 10 more }` - - `partial_images: optional number` + Represents an `assistant` that can call the model and use tools. - 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 identifier, which can be referenced in API endpoints. - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `created_at: number` - - `"low"` + The Unix timestamp (in seconds) for when the assistant was created. - - `"medium"` + - `description: string` - - `"high"` + The description of the assistant. The maximum length is 512 characters. - - `"auto"` + - `instructions: string` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + The system instructions that the assistant uses. The maximum length is 256,000 characters. - 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`. + - `metadata: Metadata` - - `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. - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - 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`. + - `model: string` - - `"1024x1024"` + 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. - - `"1024x1536"` + - `name: string` - - `"1536x1024"` + The name of the assistant. The maximum length is 256 characters. - - `"auto"` + - `object: "assistant"` - - `LocalShell object { type }` + The object type, which is always `assistant`. - A tool that allows the model to execute shell commands in a local environment. + - `"assistant"` - - `type: "local_shell"` + - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool` - The type of the local shell tool. Always `local_shell`. + 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`. - - `"local_shell"` + - `CodeInterpreterTool object { type }` - - `Shell object { type, allowed_callers, environment }` + - `type: "code_interpreter"` - A tool that allows the model to execute shell commands. + The type of tool being defined: `code_interpreter` - - `type: "shell"` + - `"code_interpreter"` - The type of the shell tool. Always `shell`. + - `FileSearchTool object { type, file_search }` - - `"shell"` + - `type: "file_search"` - - `allowed_callers: optional array of "direct" or "programmatic"` + The type of tool being defined: `file_search` - The tool invocation context(s). + - `"file_search"` - - `"direct"` + - `file_search: optional object { max_num_results, ranking_options }` - - `"programmatic"` + Overrides for the file search tool. - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + - `max_num_results: optional number` - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 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. - - `type: "container_auto"` + 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. - Automatically creates a container for this request + - `ranking_options: optional object { score_threshold, ranker }` - - `"container_auto"` + 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. - - `file_ids: optional array of string` + See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - An optional list of uploaded files to make available to your code. + - `score_threshold: number` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - The memory limit for the container. + - `ranker: optional "auto" or "default_2024_08_21"` - - `"1g"` + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `"4g"` + - `"auto"` - - `"16g"` + - `"default_2024_08_21"` - - `"64g"` + - `FunctionTool object { function, type }` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `function: FunctionDefinition` - Network access policy for the container. + - `name: string` - - `BetaContainerNetworkPolicyDisabled object { 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. - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `description: optional string` - - `skills: optional array of BetaSkillReference or BetaInlineSkill` + A description of what the function does, used by the model to choose when and how to call the function. - An optional list of skills referenced by id or inline data. + - `parameters: optional FunctionParameters` - - `BetaSkillReference object { skill_id, type, version }` + 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. - - `skill_id: string` + Omitting `parameters` defines a function with an empty parameter list. - The ID of the referenced skill. + - `strict: optional boolean` - - `type: "skill_reference"` + 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). - References a skill created with the /v1/skills endpoint. + - `type: "function"` - - `"skill_reference"` + The type of tool being defined: `function` - - `version: optional string` + - `"function"` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `response_format: optional AssistantResponseFormatOption` - - `BetaInlineSkill object { description, name, source, 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`. - - `description: 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 description of the skill. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `name: 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 name of the skill. + - `"auto"` - - `source: BetaInlineSkillSource` + `auto` is the default value - Inline skill payload + - `"auto"` - - `data: string` + - `ResponseFormatText object { type }` - Base64-encoded skill zip bundle. + Default response format. Used to generate text responses. - - `media_type: "application/zip"` + - `type: "text"` - The media type of the inline skill payload. Must be `application/zip`. + The type of response format being defined. Always `text`. - - `"application/zip"` + - `"text"` - - `type: "base64"` + - `ResponseFormatJSONObject object { type }` - The type of the inline skill source. Must be `base64`. + 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. - - `"base64"` + - `type: "json_object"` - - `type: "inline"` + The type of response format being defined. Always `json_object`. - Defines an inline skill for this request. + - `"json_object"` - - `"inline"` + - `ResponseFormatJSONSchema object { json_schema, type }` - - `BetaLocalEnvironment object { type, skills }` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - - `type: "local"` + - `json_schema: object { name, description, schema, strict }` - Use a local computer environment. + Structured Outputs configuration options, including a JSON Schema. - - `"local"` + - `name: string` - - `skills: optional array of BetaLocalSkill` + 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. - An optional list of skills. + - `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. + - `schema: optional map[unknown]` - - `name: 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 name of the skill. + - `strict: optional boolean` - - `path: 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 path to the directory containing the skill. + - `type: "json_schema"` - - `BetaContainerReference object { container_id, type }` + The type of response format being defined. Always `json_schema`. - - `container_id: string` + - `"json_schema"` - The ID of the referenced container. + - `temperature: optional number` - - `type: "container_reference"` + 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. - References a container created with the /v1/containers endpoint + - `tool_resources: optional object { code_interpreter, file_search }` - - `"container_reference"` + 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. - - `Custom object { name, type, allowed_callers, 3 more }` + - `code_interpreter: optional object { file_ids }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `file_ids: optional array of string` - - `name: 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. - The name of the custom tool, used to identify it in tool calls. + - `file_search: optional object { vector_store_ids }` - - `type: "custom"` + - `vector_store_ids: optional array of string` - The type of the custom tool. Always `custom`. + 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. - - `"custom"` + - `top_p: optional number` - - `allowed_callers: optional array of "direct" or "programmatic"` + 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 tool invocation context(s). + We generally recommend altering this or temperature but not both. - - `"direct"` +### Example - - `"programmatic"` +```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 + }' +``` - - `defer_loading: optional boolean` +#### Response - Whether this tool should be deferred and discovered via tool search. +```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 +} +``` - - `description: optional string` +### Example - Optional description of the custom tool, used to provide more context. +```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" + }' +``` - - `format: optional object { type } or object { definition, syntax, type }` +#### Response - The input format for the custom tool. Default is unconstrained text. +```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" +} +``` - - `Text object { type }` +## Delete assistant - Unconstrained free-form text. +**delete** `/assistants/{assistant_id}` - - `type: "text"` +Delete an assistant. - Unconstrained text format. Always `text`. +### Path Parameters - - `"text"` +- `assistant_id: string` - - `Grammar object { definition, syntax, type }` +### Returns - A grammar defined by the user. +- `AssistantDeleted object { id, deleted, object }` - - `definition: string` + - `id: string` - The grammar definition. + - `deleted: boolean` - - `syntax: "lark" or "regex"` + - `object: "assistant.deleted"` - The syntax of the grammar definition. One of `lark` or `regex`. + - `"assistant.deleted"` - - `"lark"` +### Example - - `"regex"` +```http +curl https://api.openai.com/v1/assistants/$ASSISTANT_ID \ + -X DELETE \ + -H 'OpenAI-Beta: assistants=v2' \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - - `type: "grammar"` +#### Response - Grammar format. Always `grammar`. +```json +{ + "id": "id", + "deleted": true, + "object": "assistant.deleted" +} +``` - - `"grammar"` +### Example - - `Namespace object { description, name, tools, type }` +```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 +``` - Groups function/custom tools under a shared namespace. +#### Response - - `description: string` +```json +{ + "id": "asst_abc123", + "object": "assistant.deleted", + "deleted": true +} +``` - A description of the namespace shown to the model. +## Domain Types - - `name: string` +### Assistant - The namespace name used in tool calls (for example, `crm`). +- `Assistant object { id, created_at, description, 10 more }` - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + Represents an `assistant` that can call the model and use tools. - The function/custom tools available inside this namespace. + - `id: string` - - `Function object { name, type, allowed_callers, 5 more }` + The identifier, which can be referenced in API endpoints. - - `name: string` + - `created_at: number` - - `type: "function"` + The Unix timestamp (in seconds) for when the assistant was created. - - `"function"` + - `description: string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The description of the assistant. The maximum length is 512 characters. - The tool invocation context(s). + - `instructions: string` - - `"direct"` + The system instructions that the assistant uses. The maximum length is 256,000 characters. - - `"programmatic"` + - `metadata: Metadata` - - `defer_loading: optional 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 this function should be deferred and discovered via tool search. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `description: optional string` + - `model: string` - - `output_schema: optional map[unknown]` + 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. - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `name: string` - - `parameters: optional unknown` + The name of the assistant. The maximum length is 256 characters. - - `strict: optional boolean` + - `object: "assistant"` - 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 object type, which is always `assistant`. - - `Custom object { name, type, allowed_callers, 3 more }` + - `"assistant"` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool` - - `name: string` + 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 name of the custom tool, used to identify it in tool calls. + - `CodeInterpreterTool object { type }` - - `type: "custom"` + - `type: "code_interpreter"` - The type of the custom tool. Always `custom`. + The type of tool being defined: `code_interpreter` - - `"custom"` + - `"code_interpreter"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `FileSearchTool object { type, file_search }` - The tool invocation context(s). + - `type: "file_search"` - - `"direct"` + The type of tool being defined: `file_search` - - `"programmatic"` + - `"file_search"` - - `defer_loading: optional boolean` + - `file_search: optional object { max_num_results, ranking_options }` - Whether this tool should be deferred and discovered via tool search. + Overrides for the file search tool. - - `description: optional string` + - `max_num_results: optional number` - Optional description of the custom tool, used to provide more context. + 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. - - `format: optional object { type } or object { definition, syntax, type }` + 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 input format for the custom tool. Default is unconstrained text. + - `ranking_options: optional object { score_threshold, ranker }` - - `Text 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. - Unconstrained free-form text. + See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `type: "text"` + - `score_threshold: number` - Unconstrained text format. 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"` - - `Grammar object { definition, syntax, type }` + The ranker to use for the file search. If not specified will use the `auto` ranker. - A grammar defined by the user. + - `"auto"` - - `definition: string` + - `"default_2024_08_21"` - The grammar definition. + - `FunctionTool object { function, type }` - - `syntax: "lark" or "regex"` + - `function: FunctionDefinition` - The syntax of the grammar definition. One of `lark` or `regex`. + - `name: string` - - `"lark"` + 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. - - `"regex"` + - `description: optional string` - - `type: "grammar"` + A description of what the function does, used by the model to choose when and how to call the function. - Grammar format. Always `grammar`. + - `parameters: optional FunctionParameters` - - `"grammar"` + 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: "namespace"` + Omitting `parameters` defines a function with an empty parameter list. - The type of the tool. Always `namespace`. + - `strict: optional boolean` - - `"namespace"` + 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). - - `ToolSearch object { type, description, execution, parameters }` + - `type: "function"` - Hosted or BYOT tool search configuration for deferred tools. + The type of tool being defined: `function` - - `type: "tool_search"` + - `"function"` - The type of the tool. Always `tool_search`. + - `response_format: optional AssistantResponseFormatOption` - - `"tool_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`. - - `description: 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). - Description shown to the model for a client-executed tool search tool. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `execution: optional "server" or "client"` + **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 tool search is executed by the server or by the client. + - `"auto"` - - `"server"` + `auto` is the default value - - `"client"` + - `"auto"` - - `parameters: optional unknown` + - `ResponseFormatText object { type }` - Parameter schema for a client-executed tool search tool. + Default response format. Used to generate text responses. - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + - `type: "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). + The type of response format being defined. Always `text`. - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `"text"` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `ResponseFormatJSONObject object { type }` - - `"web_search_preview"` + 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. - - `"web_search_preview_2025_03_11"` + - `type: "json_object"` - - `search_content_types: optional array of "text" or "image"` + The type of response format being defined. Always `json_object`. - - `"text"` + - `"json_object"` - - `"image"` + - `ResponseFormatJSONSchema object { json_schema, type }` - - `search_context_size: optional "low" or "medium" or "high"` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - 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. + - `json_schema: object { name, description, schema, strict }` - - `"low"` + Structured Outputs configuration options, including a JSON Schema. - - `"medium"` + - `name: string` - - `"high"` + 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. - - `user_location: optional object { type, city, country, 2 more }` + - `description: optional string` - The user's location. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `type: "approximate"` + - `schema: optional map[unknown]` - The type of location approximation. Always `approximate`. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `"approximate"` + - `strict: optional boolean` - - `city: optional 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). - Free text input for the city of the user, e.g. `San Francisco`. + - `type: "json_schema"` - - `country: optional string` + The type of response format being defined. Always `json_schema`. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `"json_schema"` - - `region: optional string` + - `temperature: optional number` - Free text input for the region of the user, e.g. `California`. + 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. - - `timezone: optional string` + - `tool_resources: optional object { code_interpreter, file_search }` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + 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. - - `ApplyPatch object { type, allowed_callers }` + - `code_interpreter: optional object { file_ids }` - Allows the assistant to create, delete, or update files using unified diffs. + - `file_ids: optional array of string` - - `type: "apply_patch"` + 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 tool. Always `apply_patch`. + - `file_search: optional object { vector_store_ids }` - - `"apply_patch"` + - `vector_store_ids: optional array of string` - - `allowed_callers: optional array of "direct" or "programmatic"` + 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 tool invocation context(s). + - `top_p: optional number` - - `"direct"` + 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. - - `"programmatic"` + We generally recommend altering this or temperature but not both. - - `type: "tool_search_output"` +### Assistant Deleted - The type of the item. Always `tool_search_output`. +- `AssistantDeleted object { id, deleted, object }` - - `"tool_search_output"` + - `id: string` - - `agent: optional object { agent_name }` + - `deleted: boolean` - The agent that produced this item. + - `object: "assistant.deleted"` - - `agent_name: string` + - `"assistant.deleted"` - The canonical name of the agent that produced this item. +### Assistant Stream Event - - `created_by: optional string` +- `AssistantStreamEvent = object { data, event, enabled } or object { data, event } or object { data, event } or 22 more` - The identifier of the actor that created the item. + Represents an event emitted when streaming a Run. - - `AdditionalTools object { id, role, tools, 2 more }` + Each event in a server-sent events stream has an `event` and `data` property: - - `id: string` + ``` + event: thread.created + data: {"id": "thread_123", "object": "thread", ...} + ``` - The unique ID of the additional tools item. + 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. - - `role: "unknown" or "user" or "assistant" or 5 more` + 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 role that provided the additional tools. + - `object { data, event, enabled }` - - `"unknown"` + Occurs when a new [thread](/docs/api-reference/threads/object) is created. - - `"user"` + - `data: Thread` - - `"assistant"` + Represents a thread that contains [messages](/docs/api-reference/messages). - - `"system"` + - `id: string` - - `"critic"` + The identifier, which can be referenced in API endpoints. - - `"discriminator"` + - `created_at: number` - - `"developer"` + The Unix timestamp (in seconds) for when the thread was created. - - `"tool"` + - `metadata: Metadata` - - `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. - The additional tool definitions made available at this item. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `Function object { name, parameters, strict, 5 more }` + - `object: "thread"` - 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 object type, which is always `thread`. - - `name: string` + - `"thread"` - The name of the function to call. + - `tool_resources: object { code_interpreter, file_search }` - - `parameters: map[unknown]` + 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 JSON schema object describing the parameters of the function. + - `code_interpreter: optional object { file_ids }` - - `strict: boolean` + - `file_ids: optional array of string` - Whether strict parameter validation is enforced for this function tool. + 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: "function"` + - `file_search: optional object { vector_store_ids }` - The type of the function tool. Always `function`. + - `vector_store_ids: optional array of string` - - `"function"` + 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. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `event: "thread.created"` - The tool invocation context(s). + - `"thread.created"` - - `"direct"` + - `enabled: optional boolean` - - `"programmatic"` + Whether to enable input audio transcription. - - `defer_loading: optional boolean` + - `object { data, event }` - Whether this function is deferred and loaded via tool search. + Occurs when a new [run](/docs/api-reference/runs/object) is created. - - `description: optional string` + - `data: Run` - A description of the function. Used by the model to determine whether or not to call the function. + Represents an execution run on a [thread](/docs/api-reference/threads). - - `output_schema: optional map[unknown]` + - `id: string` - A JSON schema object describing the JSON value encoded in string outputs for this function. + The identifier, which can be referenced in API endpoints. - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + - `assistant_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 [assistant](/docs/api-reference/assistants) used for execution of this run. - - `type: "file_search"` + - `cancelled_at: number` - The type of the file search tool. Always `file_search`. + The Unix timestamp (in seconds) for when the run was cancelled. - - `"file_search"` + - `completed_at: number` - - `vector_store_ids: array of string` + The Unix timestamp (in seconds) for when the run was completed. - The IDs of the vector stores to search. + - `created_at: number` - - `filters: optional object { key, type, value } or object { filters, type }` + The Unix timestamp (in seconds) for when the run was created. - A filter to apply. + - `expires_at: number` - - `ComparisonFilter object { key, type, value }` + The Unix timestamp (in seconds) for when the run will expire. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `failed_at: number` - - `key: string` + The Unix timestamp (in seconds) for when the run failed. - The key to compare against the value. + - `incomplete_details: object { reason }` - - `type: "eq" or "ne" or "gt" or 5 more` + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` - - `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 run is incomplete. This will point to which specific token limit was reached over the course of the run. - - `"eq"` + - `"max_completion_tokens"` - - `"ne"` + - `"max_prompt_tokens"` - - `"gt"` + - `instructions: string` - - `"gte"` + The instructions that the [assistant](/docs/api-reference/assistants) used for this run. - - `"lt"` + - `last_error: object { code, message }` - - `"lte"` + The last error associated with this run. Will be `null` if there are no errors. - - `"in"` + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` - - `"nin"` + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - - `value: string or number or boolean or array of string or number` + - `"server_error"` - The value to compare against the attribute key; supports string, number, or boolean types. + - `"rate_limit_exceeded"` - - `string` + - `"invalid_prompt"` - - `number` + - `message: string` - - `boolean` + A human-readable description of the error. - - `array of string or number` + - `max_completion_tokens: number` - - `string` + The maximum number of completion tokens specified to have been used over the course of the run. - - `number` + - `max_prompt_tokens: number` - - `CompoundFilter object { filters, type }` + The maximum number of prompt tokens specified to have been used over the course of the run. - Combine multiple filters using `and` or `or`. + - `metadata: Metadata` - - `filters: array of object { key, type, value } or unknown` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `ComparisonFilter object { key, type, value }` + - `model: string` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The model that the [assistant](/docs/api-reference/assistants) used for this run. - - `key: string` + - `object: "thread.run"` - The key to compare against the value. + The object type, which is always `thread.run`. - - `type: "eq" or "ne" or "gt" or 5 more` + - `"thread.run"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `parallel_tool_calls: boolean` - - `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 + Whether to enable [parallel function calling](/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `"eq"` + - `required_action: object { submit_tool_outputs, type }` - - `"ne"` + Details on the action required to continue the run. Will be `null` if no action is required. - - `"gt"` + - `submit_tool_outputs: object { tool_calls }` - - `"gte"` + Details on the tool outputs needed for this run to continue. - - `"lt"` + - `tool_calls: array of RequiredActionFunctionToolCall` - - `"lte"` + A list of the relevant tool calls. - - `"in"` + - `id: string` - - `"nin"` + 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. - - `value: string or number or boolean or array of string or number` + - `function: object { arguments, name }` - The value to compare against the attribute key; supports string, number, or boolean types. + The function definition. - - `string` + - `arguments: string` - - `number` + The arguments that the model expects you to pass to the function. - - `boolean` + - `name: string` - - `array of string or number` + The name of the function. - - `string` + - `type: "function"` - - `number` + The type of tool call the output is required for. For now, this is always `function`. - - `unknown` + - `"function"` - - `type: "and" or "or"` + - `type: "submit_tool_outputs"` - Type of operation: `and` or `or`. + For now, this is always `submit_tool_outputs`. - - `"and"` + - `"submit_tool_outputs"` - - `"or"` + - `response_format: AssistantResponseFormatOption` - - `max_num_results: 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`. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + 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). - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - Ranking options for search. + **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. - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `"auto"` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + `auto` is the default value - - `embedding_weight: number` + - `"auto"` - The weight of the embedding in the reciprocal ranking fusion. + - `ResponseFormatText object { type }` - - `text_weight: number` + Default response format. Used to generate text responses. - The weight of the text in the reciprocal ranking fusion. + - `type: "text"` - - `ranker: optional "auto" or "default-2024-11-15"` + The type of response format being defined. Always `text`. - The ranker to use for the file search. + - `"text"` - - `"auto"` + - `ResponseFormatJSONObject object { type }` - - `"default-2024-11-15"` + 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. - - `score_threshold: optional number` + - `type: "json_object"` - 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 response format being defined. Always `json_object`. - - `Computer object { type }` + - `"json_object"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `ResponseFormatJSONSchema object { json_schema, type }` - - `type: "computer"` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - The type of the computer tool. Always `computer`. + - `json_schema: object { name, description, schema, strict }` - - `"computer"` + Structured Outputs configuration options, including a JSON Schema. - - `ComputerUsePreview object { display_height, display_width, environment, type }` + - `name: string` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + 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. - - `display_height: number` + - `description: optional string` - The height of the computer display. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `display_width: number` + - `schema: optional map[unknown]` - The width of the computer display. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `environment: "windows" or "mac" or "linux" or 2 more` + - `strict: optional boolean` - The type of computer environment to control. + 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). - - `"windows"` + - `type: "json_schema"` - - `"mac"` + The type of response format being defined. Always `json_schema`. - - `"linux"` + - `"json_schema"` - - `"ubuntu"` + - `started_at: number` - - `"browser"` + The Unix timestamp (in seconds) for when the run was started. - - `type: "computer_use_preview"` + - `status: "queued" or "in_progress" or "requires_action" or 6 more` - The type of the computer use tool. Always `computer_use_preview`. + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - - `"computer_use_preview"` + - `"queued"` - - `WebSearch object { type, filters, search_context_size, user_location }` + - `"in_progress"` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `"requires_action"` - - `type: "web_search" or "web_search_2025_08_26"` + - `"cancelling"` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `"cancelled"` - - `"web_search"` + - `"failed"` - - `"web_search_2025_08_26"` + - `"completed"` - - `filters: optional object { allowed_domains }` + - `"incomplete"` - Filters for the search. + - `"expired"` - - `allowed_domains: optional array of string` + - `thread_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 [thread](/docs/api-reference/threads) that was executed on as a part of this run. - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `tool_choice: AssistantToolChoiceOption` - - `search_context_size: optional "low" or "medium" 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. - 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. + - `"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. - - `"medium"` + - `"none"` - - `"high"` + - `"auto"` - - `user_location: optional object { city, country, region, 2 more }` + - `"required"` - The approximate location of the user. + - `AssistantToolChoice object { type, function }` - - `city: optional string` + Specifies a tool the model should use. Use to force the model to call a specific tool. - Free text input for the city of the user, e.g. `San Francisco`. + - `type: "function" or "code_interpreter" or "file_search"` - - `country: optional string` + The type of the tool. If type is `function`, the function name must be set - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `"function"` - - `region: optional string` + - `"code_interpreter"` - Free text input for the region of the user, e.g. `California`. + - `"file_search"` - - `timezone: optional string` + - `function: optional AssistantToolChoiceFunction` - 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 to call. - The type of location approximation. Always `approximate`. + - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool` - - `"approximate"` + The list of tools that the [assistant](/docs/api-reference/assistants) used for this run. - - `Mcp object { server_label, type, allowed_callers, 9 more }` + - `CodeInterpreterTool object { type }` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `type: "code_interpreter"` - - `server_label: string` + The type of tool being defined: `code_interpreter` - A label for this MCP server, used to identify it in tool calls. + - `"code_interpreter"` - - `type: "mcp"` + - `FileSearchTool object { type, file_search }` - The type of the MCP tool. Always `mcp`. + - `type: "file_search"` - - `"mcp"` + 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` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + 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. - List of allowed tool names or a filter object. + 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. - - `McpAllowedTools = array of string` + - `ranking_options: optional object { score_threshold, ranker }` - A string array of allowed tool names + 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. - - `McpToolFilter object { read_only, tool_names }` + See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - A filter object to specify which tools are allowed. + - `score_threshold: number` - - `read_only: optional boolean` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - 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. + - `ranker: optional "auto" or "default_2024_08_21"` - - `tool_names: optional array of string` + The ranker to use for the file search. If not specified will use the `auto` ranker. - List of allowed tool names. + - `"auto"` - - `authorization: optional string` + - `"default_2024_08_21"` - 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. + - `FunctionTool object { function, type }` - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + - `function: FunctionDefinition` - 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + - `name: string` - Currently supported `connector_id` values are: + 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. - - 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` + - `description: optional string` - - `"connector_dropbox"` + A description of what the function does, used by the model to choose when and how to call the function. - - `"connector_gmail"` + - `parameters: optional FunctionParameters` - - `"connector_googlecalendar"` + 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. - - `"connector_googledrive"` + Omitting `parameters` defines a function with an empty parameter list. - - `"connector_microsoftteams"` + - `strict: optional boolean` - - `"connector_outlookcalendar"` + 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). - - `"connector_outlookemail"` + - `type: "function"` - - `"connector_sharepoint"` + The type of tool being defined: `function` - - `defer_loading: optional boolean` + - `"function"` - Whether this MCP tool is deferred and discovered via tool search. + - `truncation_strategy: object { type, last_messages }` - - `headers: optional map[string]` + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `type: "auto" or "last_messages"` - - `require_approval: optional object { always, never } or "always" or "never"` + 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`. - Specify which of the MCP server's tools require approval. + - `"auto"` - - `McpToolApprovalFilter object { always, never }` + - `"last_messages"` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `last_messages: optional number` - - `always: optional object { read_only, tool_names }` + The number of most recent messages from the thread when constructing the context for the run. - A filter object to specify which tools are allowed. + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - - `read_only: 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.). - 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. + - `completion_tokens: number` - - `tool_names: optional array of string` + Number of completion tokens used over the course of the run. - List of allowed tool names. + - `prompt_tokens: number` - - `never: optional object { read_only, tool_names }` + Number of prompt tokens used over the course of the run. - A filter object to specify which tools are allowed. + - `total_tokens: number` - - `read_only: optional boolean` + Total number of tokens used (prompt + completion). - 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. + - `temperature: optional number` - - `tool_names: optional array of string` + The sampling temperature used for this run. If not set, defaults to 1. - List of allowed tool names. + - `top_p: optional number` - - `McpToolApprovalSetting = "always" or "never"` + The nucleus sampling value used for this run. If not set, defaults to 1. - 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.run.created"` - - `"always"` + - `"thread.run.created"` - - `"never"` + - `object { data, event }` - - `server_description: optional string` + Occurs when a [run](/docs/api-reference/runs/object) moves to a `queued` status. - Optional description of the MCP server, used to provide more context. + - `data: Run` - - `server_url: optional string` + Represents an execution run on a [thread](/docs/api-reference/threads). - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `event: "thread.run.queued"` - - `tunnel_id: optional string` + - `"thread.run.queued"` - 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. + - `object { data, event }` - - `CodeInterpreter object { container, type, allowed_callers }` + Occurs when a [run](/docs/api-reference/runs/object) moves to an `in_progress` status. - A tool that runs Python code to help generate a response to a prompt. + - `data: Run` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + Represents an execution run on a [thread](/docs/api-reference/threads). - 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. + - `event: "thread.run.in_progress"` - - `string` + - `"thread.run.in_progress"` - The container ID. + - `object { data, event }` - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + Occurs when a [run](/docs/api-reference/runs/object) moves to a `requires_action` status. - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `data: Run` - - `type: "auto"` + Represents an execution run on a [thread](/docs/api-reference/threads). - Always `auto`. + - `event: "thread.run.requires_action"` - - `"auto"` + - `"thread.run.requires_action"` - - `file_ids: optional array of string` + - `object { data, event }` - An optional list of uploaded files to make available to your code. + Occurs when a [run](/docs/api-reference/runs/object) is completed. - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `data: Run` - The memory limit for the code interpreter container. + Represents an execution run on a [thread](/docs/api-reference/threads). - - `"1g"` + - `event: "thread.run.completed"` - - `"4g"` + - `"thread.run.completed"` - - `"16g"` + - `object { data, event }` - - `"64g"` + Occurs when a [run](/docs/api-reference/runs/object) ends with status `incomplete`. - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `data: Run` - Network access policy for the container. + Represents an execution run on a [thread](/docs/api-reference/threads). - - `BetaContainerNetworkPolicyDisabled object { type }` + - `event: "thread.run.incomplete"` - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `"thread.run.incomplete"` - - `type: "code_interpreter"` + - `object { data, event }` - The type of the code interpreter tool. Always `code_interpreter`. + Occurs when a [run](/docs/api-reference/runs/object) fails. - - `"code_interpreter"` + - `data: Run` - - `allowed_callers: optional array of "direct" or "programmatic"` + Represents an execution run on a [thread](/docs/api-reference/threads). - The tool invocation context(s). + - `event: "thread.run.failed"` - - `"direct"` + - `"thread.run.failed"` - - `"programmatic"` + - `object { data, event }` - - `ProgrammaticToolCalling object { type }` + Occurs when a [run](/docs/api-reference/runs/object) moves to a `cancelling` status. - - `type: "programmatic_tool_calling"` + - `data: Run` - The type of the tool. Always `programmatic_tool_calling`. + Represents an execution run on a [thread](/docs/api-reference/threads). - - `"programmatic_tool_calling"` + - `event: "thread.run.cancelling"` - - `ImageGeneration object { type, action, background, 9 more }` + - `"thread.run.cancelling"` - A tool that generates images using the GPT image models. + - `object { data, event }` - - `type: "image_generation"` + Occurs when a [run](/docs/api-reference/runs/object) is cancelled. - The type of the image generation tool. Always `image_generation`. + - `data: Run` - - `"image_generation"` + Represents an execution run on a [thread](/docs/api-reference/threads). - - `action: optional "generate" or "edit" or "auto"` + - `event: "thread.run.cancelled"` - Whether to generate a new image or edit an existing image. Default: `auto`. + - `"thread.run.cancelled"` - - `"generate"` + - `object { data, event }` - - `"edit"` + Occurs when a [run](/docs/api-reference/runs/object) expires. - - `"auto"` + - `data: Run` - - `background: optional "transparent" or "opaque" or "auto"` + Represents an execution run on a [thread](/docs/api-reference/threads). - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + - `event: "thread.run.expired"` - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + - `"thread.run.expired"` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `object { data, event }` - - `"transparent"` + Occurs when a [run step](/docs/api-reference/run-steps/step-object) is created. - - `"opaque"` + - `data: RunStep` - - `"auto"` + Represents a step in execution of a run. - - `input_fidelity: optional "high" or "low"` + - `id: string` - Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + The identifier of the run step, which can be referenced in API endpoints. - - `"high"` + - `assistant_id: string` - - `"low"` + The ID of the [assistant](/docs/api-reference/assistants) associated with the run step. - - `input_image_mask: optional object { file_id, image_url }` + - `cancelled_at: number` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + The Unix timestamp (in seconds) for when the run step was cancelled. - - `file_id: optional string` + - `completed_at: number` - File ID for the mask image. + The Unix timestamp (in seconds) for when the run step completed. - - `image_url: optional string` + - `created_at: number` - Base64-encoded mask image. + The Unix timestamp (in seconds) for when the run step was created. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `expired_at: number` - The image generation model to use. Default: `gpt-image-1`. + The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. - - `string` + - `failed_at: number` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + The Unix timestamp (in seconds) for when the run step failed. - The image generation model to use. Default: `gpt-image-1`. + - `last_error: object { code, message }` - - `"gpt-image-1"` + The last error associated with this run step. Will be `null` if there are no errors. - - `"gpt-image-1-mini"` + - `code: "server_error" or "rate_limit_exceeded"` - - `"gpt-image-2"` + One of `server_error` or `rate_limit_exceeded`. - - `"gpt-image-2-2026-04-21"` + - `"server_error"` - - `"gpt-image-1.5"` + - `"rate_limit_exceeded"` - - `"chatgpt-image-latest"` + - `message: string` - - `moderation: optional "auto" or "low"` + A human-readable description of the error. - Moderation level for the generated image. Default: `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. - - `output_compression: optional number` + - `object: "thread.run.step"` - Compression level for the output image. Default: 100. + The object type, which is always `thread.run.step`. - - `output_format: optional "png" or "webp" or "jpeg"` + - `"thread.run.step"` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `run_id: string` - - `"png"` + The ID of the [run](/docs/api-reference/runs) that this run step is a part of. - - `"webp"` + - `status: "in_progress" or "cancelled" or "failed" or 2 more` - - `"jpeg"` + The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. - - `partial_images: optional number` + - `"in_progress"` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `"cancelled"` - - `quality: optional "low" or "medium" or "high" or "auto"` + - `"failed"` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `"completed"` - - `"low"` + - `"expired"` - - `"medium"` + - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` - - `"high"` + The details of the run step. - - `"auto"` + - `MessageCreationStepDetails object { message_creation, type }` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + Details of the message creation by the run step. - 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`. + - `message_creation: object { message_id }` - - `string` + - `message_id: string` - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + The ID of the message that was created by this run step. - 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: "message_creation"` - - `"1024x1024"` + Always `message_creation`. - - `"1024x1536"` + - `"message_creation"` - - `"1536x1024"` + - `ToolCallsStepDetails object { tool_calls, type }` - - `"auto"` + Details of the tool call. - - `LocalShell object { type }` + - `tool_calls: array of CodeInterpreterToolCall or FileSearchToolCall or FunctionToolCall` - A tool that allows the model to execute shell commands in a local environment. + 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: "local_shell"` + - `CodeInterpreterToolCall object { id, code_interpreter, type }` - The type of the local shell tool. Always `local_shell`. + Details of the Code Interpreter tool call the run step was involved in. - - `"local_shell"` + - `id: string` - - `Shell object { type, allowed_callers, environment }` + The ID of the tool call. - A tool that allows the model to execute shell commands. + - `code_interpreter: object { input, outputs }` - - `type: "shell"` + The Code Interpreter tool call definition. - The type of the shell tool. Always `shell`. + - `input: string` - - `"shell"` + The input to the Code Interpreter tool call. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `outputs: array of object { logs, type } or object { image, type }` - The tool invocation context(s). + 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. - - `"direct"` + - `CodeInterpreterLogOutput object { logs, type }` - - `"programmatic"` + Text output from the Code Interpreter tool call as part of a run step. - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + - `logs: string` - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + The text output from the Code Interpreter tool call. - - `BetaLocalEnvironment object { type, skills }` + - `type: "logs"` - - `BetaContainerReference object { container_id, type }` + Always `logs`. - - `Custom object { name, type, allowed_callers, 3 more }` + - `"logs"` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `CodeInterpreterImageOutput object { image, type }` - - `name: string` + - `image: object { file_id }` - The name of the custom tool, used to identify it in tool calls. + - `file_id: string` - - `type: "custom"` + The [file](/docs/api-reference/files) ID of the image. - The type of the custom tool. Always `custom`. + - `type: "image"` - - `"custom"` + Always `image`. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"image"` - The tool invocation context(s). + - `type: "code_interpreter"` - - `"direct"` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - `"programmatic"` + - `"code_interpreter"` - - `defer_loading: optional boolean` + - `FileSearchToolCall object { id, file_search, type }` - Whether this tool should be deferred and discovered via tool search. + - `id: string` - - `description: optional string` + The ID of the tool call object. - Optional description of the custom tool, used to provide more context. + - `file_search: object { ranking_options, results }` - - `format: optional object { type } or object { definition, syntax, type }` + For now, this is always going to be an empty object. - The input format for the custom tool. Default is unconstrained text. + - `ranking_options: optional object { ranker, score_threshold }` - - `Text object { type }` + The ranking options for the file search. - Unconstrained free-form text. + - `ranker: "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 }` + - `score_threshold: number` - A grammar defined by the user. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `definition: string` + - `results: optional array of object { file_id, file_name, score, content }` - The grammar definition. + The results of the file search. - - `syntax: "lark" or "regex"` + - `file_id: string` - The syntax of the grammar definition. One of `lark` or `regex`. + The ID of the file that result was found in. - - `"lark"` + - `file_name: string` - - `"regex"` + The name of the file that result was found in. - - `type: "grammar"` + - `score: number` - Grammar format. Always `grammar`. + The score of the result. All values must be a floating point number between 0 and 1. - - `"grammar"` + - `content: optional array of object { text, type }` - - `Namespace object { description, name, tools, type }` + The content of the result that was found. The content is only included if requested via the include query parameter. - Groups function/custom tools under a shared namespace. + - `text: optional string` - - `description: string` + The text content of the file. - A description of the namespace shown to the model. + - `type: optional "text"` - - `name: string` + The type of the content. - The namespace name used in tool calls (for example, `crm`). + - `"text"` - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + - `type: "file_search"` - The function/custom tools available inside this namespace. + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `Function object { name, type, allowed_callers, 5 more }` + - `"file_search"` - - `name: string` + - `FunctionToolCall object { id, function, type }` - - `type: "function"` + - `id: string` - - `"function"` + The ID of the tool call object. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `function: object { arguments, name, output }` - The tool invocation context(s). + The definition of the function that was called. - - `"direct"` + - `arguments: string` - - `"programmatic"` + The arguments passed to the function. - - `defer_loading: optional boolean` + - `name: string` - Whether this function should be deferred and discovered via tool search. + The name of the function. - - `description: optional string` + - `output: string` - - `output_schema: optional map[unknown]` + The output of the function. This will be `null` if the outputs have not been [submitted](/docs/api-reference/runs/submitToolOutputs) yet. - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `type: "function"` - - `parameters: optional unknown` + The type of tool call. This is always going to be `function` for this type of tool call. - - `strict: optional boolean` + - `"function"` - Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `type: "tool_calls"` - - `Custom object { name, type, allowed_callers, 3 more }` + Always `tool_calls`. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `"tool_calls"` - - `name: string` + - `thread_id: string` - The name of the custom tool, used to identify it in tool calls. + The ID of the [thread](/docs/api-reference/threads) that was run. - - `type: "custom"` + - `type: "message_creation" or "tool_calls"` - The type of the custom tool. Always `custom`. + The type of run step, which can be either `message_creation` or `tool_calls`. - - `"custom"` + - `"message_creation"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"tool_calls"` - The tool invocation context(s). + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - - `"direct"` + Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. - - `"programmatic"` + - `completion_tokens: number` - - `defer_loading: optional boolean` + Number of completion tokens used over the course of the run step. - Whether this tool should be deferred and discovered via tool search. + - `prompt_tokens: number` - - `description: optional string` + Number of prompt tokens used over the course of the run step. - Optional description of the custom tool, used to provide more context. + - `total_tokens: number` - - `format: optional object { type } or object { definition, syntax, type }` + Total number of tokens used (prompt + completion). - The input format for the custom tool. Default is unconstrained text. + - `event: "thread.run.step.created"` - - `Text object { type }` + - `"thread.run.step.created"` - Unconstrained free-form text. + - `object { data, event }` - - `type: "text"` + Occurs when a [run step](/docs/api-reference/run-steps/step-object) moves to an `in_progress` state. - Unconstrained text format. Always `text`. + - `data: RunStep` - - `"text"` + Represents a step in execution of a run. - - `Grammar object { definition, syntax, type }` + - `event: "thread.run.step.in_progress"` - A grammar defined by the user. + - `"thread.run.step.in_progress"` - - `definition: string` + - `object { data, event }` - The grammar definition. + Occurs when parts of a [run step](/docs/api-reference/run-steps/step-object) are being streamed. - - `syntax: "lark" or "regex"` + - `data: RunStepDeltaEvent` - The syntax of the grammar definition. One of `lark` or `regex`. + Represents a run step delta i.e. any changed fields on a run step during streaming. - - `"lark"` + - `id: string` - - `"regex"` + The identifier of the run step, which can be referenced in API endpoints. - - `type: "grammar"` + - `delta: object { step_details }` - Grammar format. Always `grammar`. + The delta containing the fields that have changed on the run step. - - `"grammar"` + - `step_details: optional RunStepDeltaMessageDelta or ToolCallDeltaObject` - - `type: "namespace"` + The details of the run step. - The type of the tool. Always `namespace`. + - `RunStepDeltaMessageDelta object { type, message_creation }` - - `"namespace"` + Details of the message creation by the run step. - - `ToolSearch object { type, description, execution, parameters }` + - `type: "message_creation"` - Hosted or BYOT tool search configuration for deferred tools. + Always `message_creation`. - - `type: "tool_search"` + - `"message_creation"` - The type of the tool. Always `tool_search`. + - `message_creation: optional object { message_id }` - - `"tool_search"` + - `message_id: optional string` - - `description: optional string` + The ID of the message that was created by this run step. - Description shown to the model for a client-executed tool search tool. + - `ToolCallDeltaObject object { type, tool_calls }` - - `execution: optional "server" or "client"` + Details of the tool call. - Whether tool search is executed by the server or by the client. + - `type: "tool_calls"` - - `"server"` + Always `tool_calls`. - - `"client"` + - `"tool_calls"` - - `parameters: optional unknown` + - `tool_calls: optional array of CodeInterpreterToolCallDelta or FileSearchToolCallDelta or FunctionToolCallDelta` - Parameter schema for a client-executed tool search tool. + 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`. - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + - `CodeInterpreterToolCallDelta object { index, type, id, code_interpreter }` - 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 Code Interpreter tool call the run step was involved in. - - `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 tool call in the tool calls array. - - `"web_search_preview"` + - `type: "code_interpreter"` - - `"web_search_preview_2025_03_11"` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - `search_content_types: optional array of "text" or "image"` + - `"code_interpreter"` - - `"text"` + - `id: optional string` - - `"image"` + The ID of the tool call. - - `search_context_size: optional "low" or "medium" or "high"` + - `code_interpreter: optional object { input, outputs }` - 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 Code Interpreter tool call definition. - - `"low"` + - `input: optional string` - - `"medium"` + The input to the Code Interpreter tool call. - - `"high"` + - `outputs: optional array of CodeInterpreterLogs or CodeInterpreterOutputImage` - - `user_location: optional object { type, city, country, 2 more }` + 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 user's location. + - `CodeInterpreterLogs object { index, type, logs }` - - `type: "approximate"` + Text output from the Code Interpreter tool call as part of a run step. - The type of location approximation. Always `approximate`. + - `index: number` - - `"approximate"` + The index of the output in the outputs array. - - `city: optional string` + - `type: "logs"` - Free text input for the city of the user, e.g. `San Francisco`. + Always `logs`. - - `country: optional string` + - `"logs"` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `logs: optional string` - - `region: optional string` + The text output from the Code Interpreter tool call. - Free text input for the region of the user, e.g. `California`. + - `CodeInterpreterOutputImage object { index, type, image }` - - `timezone: optional string` + - `index: number` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The index of the output in the outputs array. - - `ApplyPatch object { type, allowed_callers }` + - `type: "image"` - Allows the assistant to create, delete, or update files using unified diffs. + Always `image`. - - `type: "apply_patch"` + - `"image"` - The type of the tool. Always `apply_patch`. + - `image: optional object { file_id }` - - `"apply_patch"` + - `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. - - `type: "additional_tools"` + - `index: number` - The type of the item. Always `additional_tools`. + The index of the tool call in the tool calls array. - - `"additional_tools"` + - `type: "file_search"` - - `agent: optional object { agent_name }` + The type of tool call. This is always going to be `file_search` for this type of tool call. - The agent that produced this item. + - `"file_search"` - - `agent_name: string` + - `id: optional string` - The canonical name of the agent that produced this item. + The ID of the tool call object. - - `Reasoning object { id, summary, type, 4 more }` + - `FunctionToolCallDelta object { index, type, id, function }` - 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](https://platform.openai.com/docs/guides/conversation-state). + - `index: number` - - `id: string` + The index of the tool call in the tool calls array. - The unique identifier of the reasoning content. + - `type: "function"` - - `summary: array of object { text, type }` + The type of tool call. This is always going to be `function` for this type of tool call. - Reasoning summary content. + - `"function"` - - `text: string` + - `id: optional string` - A summary of the reasoning output from the model so far. + The ID of the tool call object. - - `type: "summary_text"` + - `function: optional object { arguments, name, output }` - The type of the object. Always `summary_text`. + The definition of the function that was called. - - `"summary_text"` + - `arguments: optional string` - - `type: "reasoning"` + The arguments passed to the function. - The type of the object. Always `reasoning`. + - `name: optional string` - - `"reasoning"` + The name of the function. - - `agent: optional object { agent_name }` + - `output: optional string` - The agent that produced this item. + The output of the function. This will be `null` if the outputs have not been [submitted](/docs/api-reference/runs/submitToolOutputs) yet. - - `agent_name: string` + - `object: "thread.run.step.delta"` - The canonical name of the agent that produced this item. + The object type, which is always `thread.run.step.delta`. - - `content: optional array of object { text, type }` + - `"thread.run.step.delta"` - Reasoning text content. + - `event: "thread.run.step.delta"` - - `text: string` + - `"thread.run.step.delta"` - The reasoning text from the model. + - `object { data, event }` - - `type: "reasoning_text"` + Occurs when a [run step](/docs/api-reference/run-steps/step-object) is completed. - The type of the reasoning text. Always `reasoning_text`. + - `data: RunStep` - - `"reasoning_text"` + Represents a step in execution of a run. - - `encrypted_content: optional string` + - `event: "thread.run.step.completed"` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `"thread.run.step.completed"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `object { data, event }` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Occurs when a [run step](/docs/api-reference/run-steps/step-object) fails. - - `"in_progress"` + - `data: RunStep` - - `"completed"` + Represents a step in execution of a run. - - `"incomplete"` + - `event: "thread.run.step.failed"` - - `Program object { id, call_id, code, 3 more }` + - `"thread.run.step.failed"` - - `id: string` + - `object { data, event }` - The unique ID of the program item. + Occurs when a [run step](/docs/api-reference/run-steps/step-object) is cancelled. - - `call_id: string` + - `data: RunStep` - The stable call ID of the program item. + Represents a step in execution of a run. - - `code: string` + - `event: "thread.run.step.cancelled"` - The JavaScript source executed by programmatic tool calling. + - `"thread.run.step.cancelled"` - - `fingerprint: string` + - `object { data, event }` - Opaque program replay fingerprint that must be round-tripped. + Occurs when a [run step](/docs/api-reference/run-steps/step-object) expires. - - `type: "program"` + - `data: RunStep` - The type of the item. Always `program`. + Represents a step in execution of a run. - - `"program"` + - `event: "thread.run.step.expired"` - - `agent: optional object { agent_name }` + - `"thread.run.step.expired"` - The agent that produced this item. + - `object { data, event }` - - `agent_name: string` + Occurs when a [message](/docs/api-reference/messages/object) is created. - The canonical name of the agent that produced this item. + - `data: Message` - - `ProgramOutput object { id, call_id, result, 3 more }` + Represents a message within a [thread](/docs/api-reference/threads). - `id: string` - The unique ID of the program output item. - - - `call_id: string` + The identifier, which can be referenced in API endpoints. - The call ID of the program item. + - `assistant_id: string` - - `result: string` + If applicable, the ID of the [assistant](/docs/api-reference/assistants) that authored this message. - The result produced by the program item. + - `attachments: array of object { file_id, tools }` - - `status: "completed" or "incomplete"` + A list of files attached to the message, and the tools they were added to. - The terminal status of the program output item. + - `file_id: optional string` - - `"completed"` + The ID of the file to attach to the message. - - `"incomplete"` + - `tools: optional array of CodeInterpreterTool or object { type }` - - `type: "program_output"` + The tools to add this file to. - The type of the item. Always `program_output`. + - `CodeInterpreterTool object { type }` - - `"program_output"` + - `FileSearchTool object { type }` - - `agent: optional object { agent_name }` + - `type: "file_search"` - The agent that produced this item. + The type of tool being defined: `file_search` - - `agent_name: string` + - `"file_search"` - The canonical name of the agent that produced this item. + - `completed_at: number` - - `Compaction object { id, encrypted_content, type, 2 more }` + The Unix timestamp (in seconds) for when the message was completed. - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `content: array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlock or RefusalContentBlock` - - `id: string` + The content of the message in array of text and/or images. - The unique ID of the compaction item. + - `ImageFileContentBlock object { image_file, type }` - - `encrypted_content: string` + References an image [File](/docs/api-reference/files) in the content of a message. - The encrypted content that was produced by compaction. + - `image_file: ImageFile` - - `type: "compaction"` + - `file_id: string` - The type of the item. Always `compaction`. + 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. - - `"compaction"` + - `detail: optional "auto" or "low" or "high"` - - `agent: optional object { agent_name }` + 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 agent that produced this item. + - `"auto"` - - `agent_name: string` + - `"low"` - The canonical name of the agent that produced this item. + - `"high"` - - `created_by: optional string` + - `type: "image_file"` - The identifier of the actor that created the item. + Always `image_file`. - - `ImageGenerationCall object { id, result, status, 2 more }` + - `"image_file"` - An image generation request made by the model. + - `ImageURLContentBlock object { image_url, type }` - - `id: string` + References an image URL in the content of a message. - The unique ID of the image generation call. + - `image_url: ImageURL` - - `result: string` + - `url: string` - The generated image encoded in base64. + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `status: "in_progress" or "completed" or "generating" or "failed"` + - `detail: optional "auto" or "low" or "high"` - The status of the image generation 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` - - `"in_progress"` + - `"auto"` - - `"completed"` + - `"low"` - - `"generating"` + - `"high"` - - `"failed"` + - `type: "image_url"` - - `type: "image_generation_call"` + The type of the content part. - The type of the image generation call. Always `image_generation_call`. + - `"image_url"` - - `"image_generation_call"` + - `TextContentBlock object { text, type }` - - `agent: optional object { agent_name }` + The text content that is part of a message. - The agent that produced this item. + - `text: Text` - - `agent_name: string` + - `annotations: array of FileCitationAnnotation or FilePathAnnotation` - The canonical name of the agent that produced this item. + - `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` - - `CodeInterpreterCall object { id, code, container_id, 4 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. - A tool call to run code. + - `end_index: number` - - `id: string` + - `file_citation: object { file_id }` - The unique ID of the code interpreter tool call. + - `file_id: string` - - `code: string` + The ID of the specific File the citation is from. - The code to run, or null if not available. + - `start_index: number` - - `container_id: string` + - `text: string` - The ID of the container used to run the code. + The text in the message content that needs to be replaced. - - `outputs: array of object { logs, type } or object { type, url }` + - `type: "file_citation"` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + Always `file_citation`. - - `Logs object { logs, type }` + - `"file_citation"` - The logs output from the code interpreter. + - `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` - - `logs: string` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - The logs output from the code interpreter. + - `end_index: number` - - `type: "logs"` + - `file_path: object { file_id }` - The type of the output. Always `logs`. + - `file_id: string` - - `"logs"` + The ID of the file that was generated. - - `Image object { type, url }` + - `start_index: number` - The image output from the code interpreter. + - `text: string` - - `type: "image"` + The text in the message content that needs to be replaced. - The type of the output. Always `image`. + - `type: "file_path"` - - `"image"` + Always `file_path`. - - `url: string` + - `"file_path"` - The URL of the image output from the code interpreter. + - `value: string` - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + The data that makes up the text. - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `type: "text"` - - `"in_progress"` + Always `text`. - - `"completed"` + - `"text"` - - `"incomplete"` + - `RefusalContentBlock object { refusal, type }` - - `"interpreting"` + The refusal content generated by the assistant. - - `"failed"` + - `refusal: string` - - `type: "code_interpreter_call"` + - `type: "refusal"` - The type of the code interpreter tool call. Always `code_interpreter_call`. + Always `refusal`. - - `"code_interpreter_call"` + - `"refusal"` - - `agent: optional object { agent_name }` + - `created_at: number` - The agent that produced this item. + The Unix timestamp (in seconds) for when the message was created. - - `agent_name: string` + - `incomplete_at: number` - The canonical name of the agent that produced this item. + The Unix timestamp (in seconds) for when the message was marked as incomplete. - - `LocalShellCall object { id, action, call_id, 3 more }` + - `incomplete_details: object { reason }` - A tool call to run a command on the local shell. + 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 the local shell call. + The reason the message is incomplete. - - `action: object { command, env, type, 3 more }` + - `"content_filter"` - Execute a shell command on the server. + - `"max_tokens"` - - `command: array of string` + - `"run_cancelled"` - The command to run. + - `"run_expired"` - - `env: map[string]` + - `"run_failed"` - Environment variables to set for the command. + - `metadata: Metadata` - - `type: "exec"` + 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 local shell action. Always `exec`. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `"exec"` + - `object: "thread.message"` - - `timeout_ms: optional number` + The object type, which is always `thread.message`. - Optional timeout in milliseconds for the command. + - `"thread.message"` - - `user: optional string` + - `role: "user" or "assistant"` - Optional user to run the command as. + The entity that produced the message. One of `user` or `assistant`. - - `working_directory: optional string` + - `"user"` - Optional working directory to run the command in. + - `"assistant"` - - `call_id: string` + - `run_id: string` - The unique ID of the local shell tool call generated by the model. + 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. - - `status: "in_progress" or "completed" or "incomplete"` + - `status: "in_progress" or "incomplete" or "completed"` - The status of the local shell call. + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. - `"in_progress"` + - `"incomplete"` + - `"completed"` - - `"incomplete"` + - `thread_id: string` - - `type: "local_shell_call"` + The [thread](/docs/api-reference/threads) ID that this message belongs to. - The type of the local shell call. Always `local_shell_call`. + - `event: "thread.message.created"` - - `"local_shell_call"` + - `"thread.message.created"` - - `agent: optional object { agent_name }` + - `object { data, event }` + + Occurs when a [message](/docs/api-reference/messages/object) moves to an `in_progress` state. + + - `data: Message` + + Represents a message within a [thread](/docs/api-reference/threads). + + - `event: "thread.message.in_progress"` - The agent that produced this item. + - `"thread.message.in_progress"` - - `agent_name: string` + - `object { data, event }` - The canonical name of the agent that produced this item. + Occurs when parts of a [Message](/docs/api-reference/messages/object) are being streamed. - - `LocalShellCallOutput object { id, output, type, 2 more }` + - `data: MessageDeltaEvent` - The output of a local shell tool call. + Represents a message delta i.e. any changed fields on a message during streaming. - `id: string` - The unique ID of the local shell tool call generated by the model. + The identifier of the message, which can be referenced in API endpoints. - - `output: string` + - `delta: MessageDelta` - A JSON string of the output of the local shell tool call. + The delta containing the fields that have changed on the Message. - - `type: "local_shell_call_output"` + - `content: optional array of ImageFileDeltaBlock or TextDeltaBlock or RefusalDeltaBlock or ImageURLDeltaBlock` - The type of the local shell tool call output. Always `local_shell_call_output`. + The content of the message in array of text and/or images. - - `"local_shell_call_output"` + - `ImageFileDeltaBlock object { index, type, image_file }` - - `agent: optional object { agent_name }` + References an image [File](/docs/api-reference/files) in the content of a message. - The agent that produced this item. + - `index: number` - - `agent_name: string` + The index of the content part in the message. - The canonical name of the agent that produced this item. + - `type: "image_file"` - - `status: optional "in_progress" or "completed" or "incomplete"` + Always `image_file`. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `"image_file"` - - `"in_progress"` + - `image_file: optional ImageFileDelta` - - `"completed"` + - `detail: optional "auto" or "low" or "high"` - - `"incomplete"` + 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`. - - `ShellCall object { id, action, call_id, 6 more }` + - `"auto"` - A tool call that executes one or more shell commands in a managed environment. + - `"low"` - - `id: string` + - `"high"` - The unique ID of the shell tool call. Populated when this item is returned via API. + - `file_id: optional string` - - `action: object { commands, max_output_length, timeout_ms }` + 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 shell commands and limits that describe how to run the tool call. + - `TextDeltaBlock object { index, type, text }` - - `commands: array of string` + The text content that is part of a message. - - `max_output_length: number` + - `index: number` - Optional maximum number of characters to return from each command. + The index of the content part in the message. - - `timeout_ms: number` + - `type: "text"` - Optional timeout in milliseconds for the commands. + Always `text`. - - `call_id: string` + - `"text"` - The unique ID of the shell tool call generated by the model. + - `text: optional TextDelta` - - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` + - `annotations: optional array of FileCitationDeltaAnnotation or FilePathDeltaAnnotation` - Represents the use of a local environment to perform shell actions. + - `FileCitationDeltaAnnotation object { index, type, end_index, 3 more }` - - `BetaResponseLocalEnvironment object { 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. - Represents the use of a local environment to perform shell actions. + - `index: number` - - `type: "local"` + The index of the annotation in the text content part. - The environment type. Always `local`. + - `type: "file_citation"` - - `"local"` + Always `file_citation`. - - `BetaResponseContainerReference object { container_id, type }` + - `"file_citation"` - Represents a container created with /v1/containers. + - `end_index: optional number` - - `container_id: string` + - `file_citation: optional object { file_id, quote }` - - `type: "container_reference"` + - `file_id: optional string` - The environment type. Always `container_reference`. + The ID of the specific File the citation is from. - - `"container_reference"` + - `quote: optional string` - - `status: "in_progress" or "completed" or "incomplete"` + The specific quote in the file. - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `start_index: optional number` - - `"in_progress"` + - `text: optional string` - - `"completed"` + The text in the message content that needs to be replaced. - - `"incomplete"` + - `FilePathDeltaAnnotation object { index, type, end_index, 3 more }` - - `type: "shell_call"` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - The type of the item. Always `shell_call`. + - `index: number` - - `"shell_call"` + The index of the annotation in the text content part. - - `agent: optional object { agent_name }` + - `type: "file_path"` - The agent that produced this item. + Always `file_path`. - - `agent_name: string` + - `"file_path"` - The canonical name of the agent that produced this item. + - `end_index: optional number` - - `caller: optional object { type } or object { caller_id, type }` + - `file_path: optional object { file_id }` - The execution context that produced this tool call. + - `file_id: optional string` - - `Direct object { type }` + The ID of the file that was generated. - - `type: "direct"` + - `start_index: optional number` - - `"direct"` + - `text: optional string` - - `Program object { caller_id, type }` + The text in the message content that needs to be replaced. - - `caller_id: string` + - `value: optional string` - The call ID of the program item that produced this tool call. + The data that makes up the text. - - `type: "program"` + - `RefusalDeltaBlock object { index, type, refusal }` - - `"program"` + The refusal content that is part of a message. - - `created_by: optional string` + - `index: number` - The ID of the entity that created this tool call. + The index of the refusal part in the message. - - `ShellCallOutput object { id, call_id, max_output_length, 6 more }` + - `type: "refusal"` - The output of a shell tool call that was emitted. + Always `refusal`. - - `id: string` + - `"refusal"` - The unique ID of the shell call output. Populated when this item is returned via API. + - `refusal: optional string` - - `call_id: string` + - `ImageURLDeltaBlock object { index, type, image_url }` - The unique ID of the shell tool call generated by the model. + References an image URL in the content of a message. - - `max_output_length: number` + - `index: number` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + The index of the content part in the message. - - `output: array of object { outcome, stderr, stdout, created_by }` + - `type: "image_url"` - An array of shell call output contents + Always `image_url`. - - `outcome: object { type } or object { exit_code, type }` + - `"image_url"` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + - `image_url: optional ImageURLDelta` - - `Timeout object { type }` + - `detail: optional "auto" or "low" or "high"` - Indicates that the shell call exceeded its configured time limit. + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `type: "timeout"` + - `"auto"` - The outcome type. Always `timeout`. + - `"low"` - - `"timeout"` + - `"high"` - - `Exit object { exit_code, type }` + - `url: optional string` - Indicates that the shell commands finished and returned an exit code. + The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `exit_code: number` + - `role: optional "user" or "assistant"` - Exit code from the shell process. + The entity that produced the message. One of `user` or `assistant`. - - `type: "exit"` + - `"user"` - The outcome type. Always `exit`. + - `"assistant"` - - `"exit"` + - `object: "thread.message.delta"` - - `stderr: string` + The object type, which is always `thread.message.delta`. - The standard error output that was captured. + - `"thread.message.delta"` - - `stdout: string` + - `event: "thread.message.delta"` - The standard output that was captured. + - `"thread.message.delta"` - - `created_by: optional string` + - `object { data, event }` - The identifier of the actor that created the item. + Occurs when a [message](/docs/api-reference/messages/object) is completed. - - `status: "in_progress" or "completed" or "incomplete"` + - `data: Message` - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + Represents a message within a [thread](/docs/api-reference/threads). - - `"in_progress"` + - `event: "thread.message.completed"` - - `"completed"` + - `"thread.message.completed"` - - `"incomplete"` + - `object { data, event }` - - `type: "shell_call_output"` + Occurs when a [message](/docs/api-reference/messages/object) ends before it is completed. - The type of the shell call output. Always `shell_call_output`. + - `data: Message` - - `"shell_call_output"` + Represents a message within a [thread](/docs/api-reference/threads). - - `agent: optional object { agent_name }` + - `event: "thread.message.incomplete"` - The agent that produced this item. + - `"thread.message.incomplete"` - - `agent_name: string` + - `ErrorEvent object { data, event }` - The canonical name of the agent that produced this item. + Occurs when an [error](/docs/guides/error-codes#api-errors) occurs. This can happen due to an internal server error or a timeout. - - `caller: optional object { type } or object { caller_id, type }` + - `data: ErrorObject` - The execution context that produced this tool call. + - `code: string` - - `Direct object { type }` + - `message: string` - - `type: "direct"` + - `param: string` - - `"direct"` + - `type: string` - - `Program object { caller_id, type }` + - `event: "error"` - - `caller_id: string` + - `"error"` - The call ID of the program item that produced this tool call. + - `DoneEvent object { data, event }` - - `type: "program"` + Occurs when a stream ends. - - `"program"` + - `data: "[DONE]"` - - `created_by: optional string` + - `"[DONE]"` - The identifier of the actor that created the item. + - `event: "done"` - - `ApplyPatchCall object { id, call_id, operation, 5 more }` + - `"done"` - A tool call that applies file diffs by creating, deleting, or updating files. +### Code Interpreter Tool - - `id: string` +- `CodeInterpreterTool object { type }` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `type: "code_interpreter"` - - `call_id: string` + The type of tool being defined: `code_interpreter` - The unique ID of the apply patch tool call generated by the model. + - `"code_interpreter"` - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` +### File Search Tool - One of the create_file, delete_file, or update_file operations applied via apply_patch. +- `FileSearchTool object { type, file_search }` - - `CreateFile object { diff, path, type }` + - `type: "file_search"` - Instruction describing how to create a file via the apply_patch tool. + The type of tool being defined: `file_search` - - `diff: string` + - `"file_search"` - Diff to apply. + - `file_search: optional object { max_num_results, ranking_options }` - - `path: string` + Overrides for the file search tool. - Path of the file to create. + - `max_num_results: optional number` - - `type: "create_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. - Create a new file with the provided diff. + 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. - - `"create_file"` + - `ranking_options: optional object { score_threshold, ranker }` - - `DeleteFile object { path, 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. - Instruction describing how to delete a file via the apply_patch tool. + See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `path: string` + - `score_threshold: number` - Path of the file to delete. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `type: "delete_file"` + - `ranker: optional "auto" or "default_2024_08_21"` - Delete the specified file. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `"delete_file"` + - `"auto"` - - `UpdateFile object { diff, path, type }` + - `"default_2024_08_21"` - Instruction describing how to update a file via the apply_patch tool. +### Function Tool - - `diff: string` +- `FunctionTool object { function, type }` - Diff to apply. + - `function: FunctionDefinition` - - `path: string` + - `name: string` - Path of the file to update. + 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: "update_file"` + - `description: optional string` - Update an existing file with the provided diff. + A description of what the function does, used by the model to choose when and how to call the function. - - `"update_file"` + - `parameters: optional FunctionParameters` - - `status: "in_progress" or "completed"` + 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 status of the apply patch tool call. One of `in_progress` or `completed`. + Omitting `parameters` defines a function with an empty parameter list. - - `"in_progress"` + - `strict: optional boolean` - - `"completed"` + 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: "apply_patch_call"` + - `type: "function"` - The type of the item. Always `apply_patch_call`. + The type of tool being defined: `function` - - `"apply_patch_call"` + - `"function"` - - `agent: optional object { agent_name }` +### Message Stream Event - The agent that produced this item. +- `MessageStreamEvent = object { data, event } or object { data, event } or object { data, event } or 2 more` - - `agent_name: string` + Occurs when a [message](/docs/api-reference/messages/object) is created. - The canonical name of the agent that produced this item. + - `object { data, event }` - - `caller: optional object { type } or object { caller_id, type }` + Occurs when a [message](/docs/api-reference/messages/object) is created. - The execution context that produced this tool call. + - `data: Message` - - `Direct object { type }` + Represents a message within a [thread](/docs/api-reference/threads). - - `type: "direct"` + - `id: string` - - `"direct"` + The identifier, which can be referenced in API endpoints. - - `Program object { caller_id, type }` + - `assistant_id: string` - - `caller_id: string` + If applicable, the ID of the [assistant](/docs/api-reference/assistants) that authored this message. - The call ID of the program item that produced this tool call. + - `attachments: array of object { file_id, tools }` - - `type: "program"` + A list of files attached to the message, and the tools they were added to. - - `"program"` + - `file_id: optional string` - - `created_by: optional string` + The ID of the file to attach to the message. - The ID of the entity that created this tool call. + - `tools: optional array of CodeInterpreterTool or object { type }` - - `ApplyPatchCallOutput object { id, call_id, status, 5 more }` + The tools to add this file to. - The output emitted by an apply patch tool call. + - `CodeInterpreterTool object { type }` - - `id: string` + - `type: "code_interpreter"` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + The type of tool being defined: `code_interpreter` - - `call_id: string` + - `"code_interpreter"` - The unique ID of the apply patch tool call generated by the model. + - `FileSearchTool object { type }` - - `status: "completed" or "failed"` + - `type: "file_search"` - The status of the apply patch tool call output. One of `completed` or `failed`. + The type of tool being defined: `file_search` - - `"completed"` + - `"file_search"` - - `"failed"` + - `completed_at: number` - - `type: "apply_patch_call_output"` + The Unix timestamp (in seconds) for when the message was completed. - The type of the item. Always `apply_patch_call_output`. + - `content: array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlock or RefusalContentBlock` - - `"apply_patch_call_output"` + The content of the message in array of text and/or images. - - `agent: optional object { agent_name }` + - `ImageFileContentBlock object { image_file, type }` - The agent that produced this item. + References an image [File](/docs/api-reference/files) in the content of a message. - - `agent_name: string` + - `image_file: ImageFile` - The canonical name of the agent that produced this item. + - `file_id: string` - - `caller: optional object { type } or object { caller_id, 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. - The execution context that produced this tool call. + - `detail: optional "auto" or "low" or "high"` - - `Direct 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`. - - `type: "direct"` + - `"auto"` - - `"direct"` + - `"low"` - - `Program object { caller_id, type }` + - `"high"` - - `caller_id: string` + - `type: "image_file"` - The call ID of the program item that produced this tool call. + Always `image_file`. - - `type: "program"` + - `"image_file"` - - `"program"` + - `ImageURLContentBlock object { image_url, type }` - - `created_by: optional string` + References an image URL in the content of a message. - The ID of the entity that created this tool call output. + - `image_url: ImageURL` - - `output: optional string` + - `url: string` - Optional textual output returned by the apply patch tool. + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `McpListTools object { id, server_label, tools, 3 more }` + - `detail: optional "auto" or "low" or "high"` - A list of tools available on an MCP server. + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - - `id: string` + - `"auto"` - The unique ID of the list. + - `"low"` - - `server_label: string` + - `"high"` - The label of the MCP server. + - `type: "image_url"` - - `tools: array of object { input_schema, name, annotations, description }` + The type of the content part. - The tools available on the server. + - `"image_url"` - - `input_schema: unknown` + - `TextContentBlock object { text, type }` - The JSON schema describing the tool's input. + The text content that is part of a message. - - `name: string` + - `text: Text` - The name of the tool. + - `annotations: array of FileCitationAnnotation or FilePathAnnotation` - - `annotations: optional unknown` + - `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` - Additional annotations about the tool. + 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. - - `description: optional string` + - `end_index: number` - The description of the tool. + - `file_citation: object { file_id }` - - `type: "mcp_list_tools"` + - `file_id: string` - The type of the item. Always `mcp_list_tools`. + The ID of the specific File the citation is from. - - `"mcp_list_tools"` + - `start_index: number` - - `agent: optional object { agent_name }` + - `text: string` - The agent that produced this item. + The text in the message content that needs to be replaced. - - `agent_name: string` + - `type: "file_citation"` - The canonical name of the agent that produced this item. + Always `file_citation`. - - `error: optional string` + - `"file_citation"` - Error message if the server could not list tools. + - `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` - - `McpApprovalRequest object { id, arguments, name, 3 more }` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - A request for human approval of a tool invocation. + - `end_index: number` - - `id: string` + - `file_path: object { file_id }` - The unique ID of the approval request. + - `file_id: string` - - `arguments: string` + The ID of the file that was generated. - A JSON string of arguments for the tool. + - `start_index: number` - - `name: string` + - `text: string` - The name of the tool to run. + The text in the message content that needs to be replaced. - - `server_label: string` + - `type: "file_path"` - The label of the MCP server making the request. + Always `file_path`. - - `type: "mcp_approval_request"` + - `"file_path"` - The type of the item. Always `mcp_approval_request`. + - `value: string` - - `"mcp_approval_request"` + The data that makes up the text. - - `agent: optional object { agent_name }` + - `type: "text"` - The agent that produced this item. + Always `text`. - - `agent_name: string` + - `"text"` - The canonical name of the agent that produced this item. + - `RefusalContentBlock object { refusal, type }` - - `McpApprovalResponse object { id, approval_request_id, approve, 3 more }` + The refusal content generated by the assistant. - A response to an MCP approval request. + - `refusal: string` - - `id: string` + - `type: "refusal"` - The unique ID of the approval response + Always `refusal`. - - `approval_request_id: string` + - `"refusal"` - The ID of the approval request being answered. + - `created_at: number` - - `approve: boolean` + The Unix timestamp (in seconds) for when the message was created. - Whether the request was approved. + - `incomplete_at: number` - - `type: "mcp_approval_response"` + The Unix timestamp (in seconds) for when the message was marked as incomplete. - The type of the item. Always `mcp_approval_response`. + - `incomplete_details: object { reason }` - - `"mcp_approval_response"` + On an incomplete message, details about why the message is incomplete. - - `agent: optional object { agent_name }` + - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` - The agent that produced this item. + The reason the message is incomplete. - - `agent_name: string` + - `"content_filter"` - The canonical name of the agent that produced this item. + - `"max_tokens"` - - `reason: optional string` + - `"run_cancelled"` - Optional reason for the decision. + - `"run_expired"` - - `McpCall object { id, arguments, name, 7 more }` + - `"run_failed"` - An invocation of a tool on an MCP server. + - `metadata: Metadata` - - `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 ID of the tool call. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `arguments: string` + - `object: "thread.message"` - A JSON string of the arguments passed to the tool. + The object type, which is always `thread.message`. - - `name: string` + - `"thread.message"` - The name of the tool that was run. + - `role: "user" or "assistant"` - - `server_label: string` + The entity that produced the message. One of `user` or `assistant`. - The label of the MCP server running the tool. + - `"user"` - - `type: "mcp_call"` + - `"assistant"` - The type of the item. Always `mcp_call`. + - `run_id: string` - - `"mcp_call"` + 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. - - `agent: optional object { agent_name }` + - `status: "in_progress" or "incomplete" or "completed"` - The agent that produced this item. + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. - - `agent_name: string` + - `"in_progress"` - The canonical name of the agent that produced this item. + - `"incomplete"` - - `approval_request_id: optional string` + - `"completed"` - 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. + - `thread_id: string` - - `error: optional string` + The [thread](/docs/api-reference/threads) ID that this message belongs to. - The error from the tool call, if any. + - `event: "thread.message.created"` - - `output: optional string` + - `"thread.message.created"` - The output from the tool call. + - `object { data, event }` - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + Occurs when a [message](/docs/api-reference/messages/object) moves to an `in_progress` state. - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `data: Message` - - `"in_progress"` + Represents a message within a [thread](/docs/api-reference/threads). - - `"completed"` + - `event: "thread.message.in_progress"` - - `"incomplete"` + - `"thread.message.in_progress"` - - `"calling"` + - `object { data, event }` - - `"failed"` + Occurs when parts of a [Message](/docs/api-reference/messages/object) are being streamed. - - `CustomToolCall object { id, call_id, input, 7 more }` + - `data: MessageDeltaEvent` + + Represents a message delta i.e. any changed fields on a message during streaming. - `id: string` - The unique ID of the custom tool call item. + The identifier of the message, which can be referenced in API endpoints. - - `call_id: string` + - `delta: MessageDelta` - An identifier used to map this custom tool call to a tool call output. + The delta containing the fields that have changed on the Message. - - `input: string` + - `content: optional array of ImageFileDeltaBlock or TextDeltaBlock or RefusalDeltaBlock or ImageURLDeltaBlock` - The input for the custom tool call generated by the model. + The content of the message in array of text and/or images. - - `name: string` + - `ImageFileDeltaBlock object { index, type, image_file }` - The name of the custom tool being called. + References an image [File](/docs/api-reference/files) in the content of a message. - - `status: "in_progress" or "completed" or "incomplete"` + - `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 in the message. - - `"in_progress"` + - `type: "image_file"` - - `"completed"` + Always `image_file`. - - `"incomplete"` + - `"image_file"` - - `type: "custom_tool_call"` + - `image_file: optional ImageFileDelta` - The type of the custom tool call. Always `custom_tool_call`. + - `detail: optional "auto" or "low" or "high"` - - `"custom_tool_call"` + 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: optional object { agent_name }` + - `"auto"` - The agent that produced this item. + - `"low"` - - `agent_name: string` + - `"high"` - The canonical name of the agent that produced this item. + - `file_id: optional string` - - `caller: optional object { type } or object { caller_id, 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. - The execution context that produced this tool call. + - `TextDeltaBlock object { index, type, text }` - - `Direct object { type }` + The text content that is part of a message. - - `type: "direct"` + - `index: number` - - `"direct"` + The index of the content part in the message. - - `Program object { caller_id, type }` + - `type: "text"` - - `caller_id: string` + Always `text`. - The call ID of the program item that produced this tool call. + - `"text"` - - `type: "program"` + - `text: optional TextDelta` - - `"program"` + - `annotations: optional array of FileCitationDeltaAnnotation or FilePathDeltaAnnotation` - - `created_by: optional string` + - `FileCitationDeltaAnnotation object { index, type, end_index, 3 more }` - The identifier of the actor that created the item. + 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. - - `namespace: optional string` + - `index: number` - The namespace of the custom tool being called. + The index of the annotation in the text content part. - - `CustomToolCallOutput object { id, call_id, output, 5 more }` + - `type: "file_citation"` - - `id: string` + Always `file_citation`. - The unique ID of the custom tool call output item. + - `"file_citation"` - - `call_id: string` + - `end_index: optional number` - The call ID, used to map this custom tool call output to a custom tool call. + - `file_citation: optional object { file_id, quote }` - - `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 specific File the citation is from. - - `StringOutput = string` + - `quote: optional string` - A string of the output of the custom tool call. + The specific quote in the file. - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `start_index: optional number` - Text, image, or file output of the custom tool call. + - `text: optional string` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + The text in the message content that needs to be replaced. - A text input to the model. + - `FilePathDeltaAnnotation object { index, type, end_index, 3 more }` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `index: number` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + The index of the annotation in the text content part. - A file input to the model. + - `type: "file_path"` - - `status: "in_progress" or "completed" or "incomplete"` + Always `file_path`. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"file_path"` - - `"in_progress"` + - `end_index: optional number` - - `"completed"` + - `file_path: optional object { file_id }` - - `"incomplete"` + - `file_id: optional string` - - `type: "custom_tool_call_output"` + The ID of the file that was generated. - The type of the custom tool call output. Always `custom_tool_call_output`. + - `start_index: optional number` - - `"custom_tool_call_output"` + - `text: optional string` - - `agent: optional object { agent_name }` + The text in the message content that needs to be replaced. - The agent that produced this item. + - `value: optional string` - - `agent_name: string` + The data that makes up the text. - The canonical name of the agent that produced this item. + - `RefusalDeltaBlock object { index, type, refusal }` - - `caller: optional object { type } or object { caller_id, type }` + The refusal content that is part of a message. - The execution context that produced this tool call. + - `index: number` - - `Direct object { type }` + The index of the refusal part in the message. - - `type: "direct"` + - `type: "refusal"` - The caller type. Always `direct`. + Always `refusal`. - - `"direct"` + - `"refusal"` - - `Program object { caller_id, type }` + - `refusal: optional string` - - `caller_id: string` + - `ImageURLDeltaBlock object { index, type, image_url }` - The call ID of the program item that produced this tool call. + References an image URL in the content of a message. - - `type: "program"` + - `index: number` - The caller type. Always `program`. + The index of the content part in the message. - - `"program"` + - `type: "image_url"` - - `created_by: optional string` + Always `image_url`. - The identifier of the actor that created the item. + - `"image_url"` - - `first_id: string` + - `image_url: optional ImageURLDelta` - The ID of the first item in the list. + - `detail: optional "auto" or "low" or "high"` - - `has_more: boolean` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. - Whether there are more items available. + - `"auto"` - - `last_id: string` + - `"low"` - The ID of the last item in the list. + - `"high"` - - `object: "list"` + - `url: optional string` - The type of object returned, must be `list`. + The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `"list"` + - `role: optional "user" or "assistant"` -### Example + The entity that produced the message. One of `user` or `assistant`. -```http -curl https://api.openai.com/v1/responses/$RESPONSE_ID/input_items \ - -H 'OpenAI-Beta: assistants=v2' \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + - `"user"` -#### Response + - `"assistant"` -```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" -} -``` + - `object: "thread.message.delta"` -### Example + The object type, which is always `thread.message.delta`. -```http -curl https://api.openai.com/v1/responses/resp_abc123/input_items \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + - `"thread.message.delta"` -#### Response + - `event: "thread.message.delta"` -```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 -} -``` + - `"thread.message.delta"` -## Domain Types + - `object { data, event }` -### Beta Response Item List + Occurs when a [message](/docs/api-reference/messages/object) is completed. -- `BetaResponseItemList object { data, first_id, has_more, 2 more }` + - `data: Message` - A list of Response items. + Represents a message within a [thread](/docs/api-reference/threads). - - `data: array of BetaResponseInputMessageItem or BetaResponseOutputMessage or object { id, queries, status, 3 more } or 29 more` + - `event: "thread.message.completed"` - A list of items used to generate this response. + - `"thread.message.completed"` - - `BetaResponseInputMessageItem object { id, content, role, 3 more }` + - `object { data, event }` - - `id: string` + Occurs when a [message](/docs/api-reference/messages/object) ends before it is completed. - The unique ID of the message input. + - `data: Message` - - `content: BetaResponseInputMessageContentList` + Represents a message within a [thread](/docs/api-reference/threads). - A list of one or many input items to the model, containing different content - types. + - `event: "thread.message.incomplete"` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `"thread.message.incomplete"` - A text input to the model. +### Run Step Stream Event - - `text: string` +- `RunStepStreamEvent = object { data, event } or object { data, event } or object { data, event } or 4 more` - The text input to the model. + Occurs when a [run step](/docs/api-reference/run-steps/step-object) is created. - - `type: "input_text"` + - `object { data, event }` - The type of the input item. Always `input_text`. + Occurs when a [run step](/docs/api-reference/run-steps/step-object) is created. - - `"input_text"` + - `data: RunStep` - - `prompt_cache_breakpoint: optional object { mode }` + Represents a step in execution of a 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. + - `id: string` - - `mode: "explicit"` + The identifier of the run step, which can be referenced in API endpoints. - The breakpoint mode. Always `explicit`. + - `assistant_id: string` - - `"explicit"` + The ID of the [assistant](/docs/api-reference/assistants) associated with the run step. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `cancelled_at: number` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The Unix timestamp (in seconds) for when the run step was cancelled. - - `detail: "low" or "high" or "auto" or "original"` + - `completed_at: number` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The Unix timestamp (in seconds) for when the run step completed. - - `"low"` + - `created_at: number` - - `"high"` + The Unix timestamp (in seconds) for when the run step was created. - - `"auto"` + - `expired_at: number` - - `"original"` + The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. - - `type: "input_image"` + - `failed_at: number` - The type of the input item. Always `input_image`. + The Unix timestamp (in seconds) for when the run step failed. - - `"input_image"` + - `last_error: object { code, message }` - - `file_id: optional string` + The last error associated with this run step. Will be `null` if there are no errors. - The ID of the file to be sent to the model. + - `code: "server_error" or "rate_limit_exceeded"` - - `image_url: optional string` + One of `server_error` or `rate_limit_exceeded`. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `"server_error"` - - `prompt_cache_breakpoint: optional object { mode }` + - `"rate_limit_exceeded"` - Marks the exact end of a reusable 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"` + A human-readable description of the error. - The breakpoint mode. Always `explicit`. + - `metadata: 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. - - `BetaResponseInputFile 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. + - `object: "thread.run.step"` - - `type: "input_file"` + The object type, which is always `thread.run.step`. - The type of the input item. Always `input_file`. + - `"thread.run.step"` - - `"input_file"` + - `run_id: string` - - `detail: optional "auto" or "low" or "high"` + The ID of the [run](/docs/api-reference/runs) that this run step is a part of. - 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 "cancelled" or "failed" or 2 more` - - `"auto"` + The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. - - `"low"` + - `"in_progress"` - - `"high"` + - `"cancelled"` - - `file_data: optional string` + - `"failed"` - The content of the file to be sent to the model. + - `"completed"` - - `file_id: optional string` + - `"expired"` - The ID of the file to be sent to the model. + - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` - - `file_url: optional string` + The details of the run step. - The URL of the file to be sent to the model. + - `MessageCreationStepDetails object { message_creation, type }` - - `filename: optional string` + Details of the message creation by the run step. - The name of the file to be sent to the model. + - `message_creation: object { message_id }` - - `prompt_cache_breakpoint: optional object { mode }` + - `message_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 ID of the message that was created by this run step. - - `mode: "explicit"` + - `type: "message_creation"` - The breakpoint mode. Always `explicit`. + Always `message_creation`. - - `"explicit"` + - `"message_creation"` - - `role: "user" or "system" or "developer"` + - `ToolCallsStepDetails object { tool_calls, type }` - The role of the message input. One of `user`, `system`, or `developer`. + Details of the tool call. - - `"user"` + - `tool_calls: array of CodeInterpreterToolCall or FileSearchToolCall or FunctionToolCall` - - `"system"` + 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`. - - `"developer"` + - `CodeInterpreterToolCall object { id, code_interpreter, type }` - - `type: "message"` + Details of the Code Interpreter tool call the run step was involved in. - The type of the message input. Always set to `message`. + - `id: string` - - `"message"` + The ID of the tool call. - - `agent: optional object { agent_name }` + - `code_interpreter: object { input, outputs }` - The agent that produced this item. + The Code Interpreter tool call definition. - - `agent_name: string` + - `input: string` - The canonical name of the agent that produced this item. + The input to the Code Interpreter tool call. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `outputs: array of object { logs, type } or object { image, type }` - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + 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. - - `"in_progress"` + - `CodeInterpreterLogOutput object { logs, type }` - - `"completed"` + Text output from the Code Interpreter tool call as part of a run step. - - `"incomplete"` + - `logs: string` - - `BetaResponseOutputMessage object { id, content, role, 4 more }` + The text output from the Code Interpreter tool call. - An output message from the model. + - `type: "logs"` - - `id: string` + Always `logs`. - The unique ID of the output message. + - `"logs"` - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + - `CodeInterpreterImageOutput object { image, type }` - The content of the output message. + - `image: object { file_id }` - - `BetaResponseOutputText object { annotations, text, type, logprobs }` + - `file_id: string` - A text output from the model. + The [file](/docs/api-reference/files) ID of the image. - - `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: "image"` - The annotations of the text output. + Always `image`. - - `FileCitation object { file_id, filename, index, type }` + - `"image"` - A citation to a file. + - `type: "code_interpreter"` - - `file_id: 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. + - `"code_interpreter"` - - `filename: string` + - `FileSearchToolCall object { id, file_search, type }` - The filename of the file cited. + - `id: string` - - `index: number` + The ID of the tool call object. - The index of the file in the list of files. + - `file_search: object { ranking_options, results }` - - `type: "file_citation"` + For now, this is always going to be an empty object. - The type of the file citation. Always `file_citation`. + - `ranking_options: optional object { ranker, score_threshold }` - - `"file_citation"` + The ranking options for the file search. - - `URLCitation object { end_index, start_index, title, 2 more }` + - `ranker: "auto" or "default_2024_08_21"` - A citation for a web resource used to generate a model response. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `end_index: number` + - `"auto"` - The index of the last character of the URL citation in the message. + - `"default_2024_08_21"` - - `start_index: number` + - `score_threshold: number` - The index of the first character of the URL citation in the message. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `title: string` + - `results: optional array of object { file_id, file_name, score, content }` - The title of the web resource. + The results of the file search. - - `type: "url_citation"` + - `file_id: string` + + The ID of the file that result was found in. - The type of the URL citation. Always `url_citation`. + - `file_name: string` - - `"url_citation"` + The name of the file that result was found in. - - `url: string` + - `score: number` - The URL of the web resource. + The score of the result. All values must be a floating point number between 0 and 1. - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + - `content: optional array of object { text, type }` - A citation for a container file used to generate a model response. + The content of the result that was found. The content is only included if requested via the include query parameter. - - `container_id: string` + - `text: optional string` - The ID of the container file. + The text content of the file. - - `end_index: number` + - `type: optional "text"` - The index of the last character of the container file citation in the message. + The type of the content. - - `file_id: string` + - `"text"` - The ID of the file. + - `type: "file_search"` - - `filename: string` + The type of tool call. This is always going to be `file_search` for this type of tool call. - The filename of the container file cited. + - `"file_search"` - - `start_index: number` + - `FunctionToolCall object { id, function, type }` - The index of the first character of the container file citation in the message. + - `id: string` - - `type: "container_file_citation"` + The ID of the tool call object. - The type of the container file citation. Always `container_file_citation`. + - `function: object { arguments, name, output }` - - `"container_file_citation"` + The definition of the function that was called. - - `FilePath object { file_id, index, type }` + - `arguments: string` - A path to a file. + The arguments passed to the function. - - `file_id: string` + - `name: string` - The ID of the file. + The name of the function. - - `index: number` + - `output: string` - The index of the file in the list of files. + The output of the function. This will be `null` if the outputs have not been [submitted](/docs/api-reference/runs/submitToolOutputs) yet. - - `type: "file_path"` + - `type: "function"` - The type of the file path. Always `file_path`. + The type of tool call. This is always going to be `function` for this type of tool call. - - `"file_path"` + - `"function"` - - `text: string` + - `type: "tool_calls"` - The text output from the model. + Always `tool_calls`. - - `type: "output_text"` + - `"tool_calls"` - The type of the output text. Always `output_text`. + - `thread_id: string` - - `"output_text"` + The ID of the [thread](/docs/api-reference/threads) that was run. - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + - `type: "message_creation" or "tool_calls"` - - `token: string` + The type of run step, which can be either `message_creation` or `tool_calls`. - - `bytes: array of number` + - `"message_creation"` - - `logprob: number` + - `"tool_calls"` - - `top_logprobs: array of object { token, bytes, logprob }` + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - - `token: string` + Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. - - `bytes: array of number` + - `completion_tokens: number` - - `logprob: number` + Number of completion tokens used over the course of the run step. - - `BetaResponseOutputRefusal object { refusal, type }` + - `prompt_tokens: number` - A refusal from the model. + Number of prompt tokens used over the course of the run step. - - `refusal: string` + - `total_tokens: number` - The refusal explanation from the model. + Total number of tokens used (prompt + completion). - - `type: "refusal"` + - `event: "thread.run.step.created"` - The type of the refusal. Always `refusal`. + - `"thread.run.step.created"` - - `"refusal"` + - `object { data, event }` - - `role: "assistant"` + Occurs when a [run step](/docs/api-reference/run-steps/step-object) moves to an `in_progress` state. - The role of the output message. Always `assistant`. + - `data: RunStep` - - `"assistant"` + Represents a step in execution of a run. - - `status: "in_progress" or "completed" or "incomplete"` + - `event: "thread.run.step.in_progress"` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `"thread.run.step.in_progress"` - - `"in_progress"` + - `object { data, event }` - - `"completed"` + Occurs when parts of a [run step](/docs/api-reference/run-steps/step-object) are being streamed. - - `"incomplete"` + - `data: RunStepDeltaEvent` - - `type: "message"` + Represents a run step delta i.e. any changed fields on a run step during streaming. - The type of the output message. Always `message`. + - `id: string` - - `"message"` + The identifier of the run step, which can be referenced in API endpoints. - - `agent: optional object { agent_name }` + - `delta: object { step_details }` - The agent that produced this item. + The delta containing the fields that have changed on the run step. - - `agent_name: string` + - `step_details: optional RunStepDeltaMessageDelta or ToolCallDeltaObject` - The canonical name of the agent that produced this item. + The details of the run step. - - `phase: optional "commentary" or "final_answer"` + - `RunStepDeltaMessageDelta object { type, message_creation }` - 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. + Details of the message creation by the run step. - - `"commentary"` + - `type: "message_creation"` - - `"final_answer"` + Always `message_creation`. - - `FileSearchCall object { id, queries, status, 3 more }` + - `"message_creation"` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `message_creation: optional object { message_id }` - - `id: string` + - `message_id: optional string` - The unique ID of the file search tool call. + The ID of the message that was created by this run step. - - `queries: array of string` + - `ToolCallDeltaObject object { type, tool_calls }` - The queries used to search for files. + Details of the tool call. - - `status: "in_progress" or "searching" or "completed" or 2 more` + - `type: "tool_calls"` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + Always `tool_calls`. - - `"in_progress"` + - `"tool_calls"` - - `"searching"` + - `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 }` - - `"failed"` + Details of the Code Interpreter tool call the run step was involved in. - - `type: "file_search_call"` + - `index: number` - The type of the file search tool call. Always `file_search_call`. + The index of the tool call in the tool calls array. - - `"file_search_call"` + - `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. - - `results: optional array of object { attributes, file_id, filename, 2 more }` + - `code_interpreter: optional object { input, outputs }` - The results of the file search tool call. + The Code Interpreter tool call definition. - - `attributes: optional map[string or number or boolean]` + - `input: 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 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 }` - - `file_id: optional string` + Text output from the Code Interpreter tool call as part of a run step. - The unique ID of the file. + - `index: number` - - `filename: optional string` + The index of the output in the outputs array. - The name of the file. + - `type: "logs"` - - `score: optional number` + Always `logs`. - The relevance score of the file - a value between 0 and 1. + - `"logs"` - - `text: optional string` + - `logs: optional string` - The text that was retrieved from the file. + The text output from the Code Interpreter tool call. - - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` + - `CodeInterpreterOutputImage object { index, type, image }` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + - `index: number` - - `id: string` + The index of the output in the outputs array. - The unique ID of the computer call. + - `type: "image"` - - `call_id: string` + Always `image`. - An identifier used when responding to the tool call with output. + - `"image"` - - `pending_safety_checks: array of object { id, code, message }` + - `image: optional object { file_id }` - The pending safety checks for the computer call. + - `file_id: optional string` - - `id: string` + The [file](/docs/api-reference/files) ID of the image. - The ID of the pending safety check. + - `FileSearchToolCallDelta object { file_search, index, type, id }` - - `code: optional string` + - `file_search: unknown` - The type of the pending safety check. + For now, this is always going to be an empty object. - - `message: optional string` + - `index: number` - Details about the pending safety check. + The index of the tool call in the tool calls array. - - `status: "in_progress" or "completed" or "incomplete"` + - `type: "file_search"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `"in_progress"` + - `"file_search"` - - `"completed"` + - `id: optional string` - - `"incomplete"` + The ID of the tool call object. - - `type: "computer_call"` + - `FunctionToolCallDelta object { index, type, id, function }` - The type of the computer call. Always `computer_call`. + - `index: number` - - `"computer_call"` + The index of the tool call in the tool calls array. - - `action: optional BetaComputerAction` + - `type: "function"` - A click action. + The type of tool call. This is always going to be `function` for this type of tool call. - - `Click object { button, type, x, 2 more }` + - `"function"` - A click action. + - `id: optional string` - - `button: "left" or "right" or "wheel" or 2 more` + The ID of the tool call object. - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `function: optional object { arguments, name, output }` - - `"left"` + The definition of the function that was called. - - `"right"` + - `arguments: optional string` - - `"wheel"` + The arguments passed to the function. - - `"back"` + - `name: optional string` - - `"forward"` + The name of the function. - - `type: "click"` + - `output: optional string` - Specifies the event type. For a click action, this property is always `click`. + The output of the function. This will be `null` if the outputs have not been [submitted](/docs/api-reference/runs/submitToolOutputs) yet. - - `"click"` + - `object: "thread.run.step.delta"` - - `x: number` + The object type, which is always `thread.run.step.delta`. - The x-coordinate where the click occurred. + - `"thread.run.step.delta"` - - `y: number` + - `event: "thread.run.step.delta"` - The y-coordinate where the click occurred. + - `"thread.run.step.delta"` - - `keys: optional array of string` + - `object { data, event }` - The keys being held while clicking. + Occurs when a [run step](/docs/api-reference/run-steps/step-object) is completed. - - `DoubleClick object { keys, type, x, y }` + - `data: RunStep` - A double click action. + Represents a step in execution of a run. - - `keys: array of string` + - `event: "thread.run.step.completed"` - The keys being held while double-clicking. + - `"thread.run.step.completed"` - - `type: "double_click"` + - `object { data, event }` - Specifies the event type. For a double click action, this property is always set to `double_click`. + Occurs when a [run step](/docs/api-reference/run-steps/step-object) fails. - - `"double_click"` + - `data: RunStep` - - `x: number` + Represents a step in execution of a run. - The x-coordinate where the double click occurred. + - `event: "thread.run.step.failed"` - - `y: number` + - `"thread.run.step.failed"` - The y-coordinate where the double click occurred. + - `object { data, event }` - - `Drag object { path, type, keys }` + Occurs when a [run step](/docs/api-reference/run-steps/step-object) is cancelled. - A drag action. + - `data: RunStep` - - `path: array of object { x, y }` + Represents a step in execution of a run. - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `event: "thread.run.step.cancelled"` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `"thread.run.step.cancelled"` - - `x: number` + - `object { data, event }` - The x-coordinate. + Occurs when a [run step](/docs/api-reference/run-steps/step-object) expires. - - `y: number` + - `data: RunStep` - The y-coordinate. + Represents a step in execution of a run. - - `type: "drag"` + - `event: "thread.run.step.expired"` - Specifies the event type. For a drag action, this property is always set to `drag`. + - `"thread.run.step.expired"` - - `"drag"` +### Run Stream Event - - `keys: optional array of string` +- `RunStreamEvent = object { data, event } or object { data, event } or object { data, event } or 7 more` - The keys being held while dragging the mouse. + Occurs when a new [run](/docs/api-reference/runs/object) is created. - - `Keypress object { keys, type }` + - `object { data, event }` - A collection of keypresses the model would like to perform. + Occurs when a new [run](/docs/api-reference/runs/object) is created. - - `keys: array of string` + - `data: Run` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + Represents an execution run on a [thread](/docs/api-reference/threads). - - `type: "keypress"` + - `id: string` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + The identifier, which can be referenced in API endpoints. - - `"keypress"` + - `assistant_id: string` - - `Move object { type, x, y, keys }` + The ID of the [assistant](/docs/api-reference/assistants) used for execution of this run. - A mouse move action. + - `cancelled_at: number` - - `type: "move"` + The Unix timestamp (in seconds) for when the run was cancelled. - Specifies the event type. For a move action, this property is always set to `move`. + - `completed_at: number` - - `"move"` + The Unix timestamp (in seconds) for when the run was completed. - - `x: number` + - `created_at: number` - The x-coordinate to move to. + The Unix timestamp (in seconds) for when the run was created. - - `y: number` + - `expires_at: number` - The y-coordinate to move to. + The Unix timestamp (in seconds) for when the run will expire. - - `keys: optional array of string` + - `failed_at: number` - The keys being held while moving the mouse. + The Unix timestamp (in seconds) for when the run failed. - - `Screenshot object { type }` + - `incomplete_details: object { reason }` - A screenshot action. + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - - `type: "screenshot"` + - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - - `"screenshot"` + - `"max_completion_tokens"` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `"max_prompt_tokens"` - A scroll action. + - `instructions: string` - - `scroll_x: number` + The instructions that the [assistant](/docs/api-reference/assistants) used for this run. - The horizontal scroll distance. + - `last_error: object { code, message }` - - `scroll_y: number` + The last error associated with this run. Will be `null` if there are no errors. - The vertical scroll distance. + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` - - `type: "scroll"` + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `"server_error"` - - `"scroll"` + - `"rate_limit_exceeded"` - - `x: number` + - `"invalid_prompt"` - The x-coordinate where the scroll occurred. + - `message: string` - - `y: number` + A human-readable description of the error. - The y-coordinate where the scroll occurred. + - `max_completion_tokens: number` - - `keys: optional array of string` + The maximum number of completion tokens specified to have been used over the course of the run. - The keys being held while scrolling. + - `max_prompt_tokens: number` - - `Type object { text, type }` + The maximum number of prompt tokens specified to have been used over the course of the run. - An action to type in text. + - `metadata: Metadata` - - `text: 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 text to type. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `type: "type"` + - `model: string` - Specifies the event type. For a type action, this property is always set to `type`. + The model that the [assistant](/docs/api-reference/assistants) used for this run. - - `"type"` + - `object: "thread.run"` - - `Wait object { type }` + The object type, which is always `thread.run`. - A wait action. + - `"thread.run"` - - `type: "wait"` + - `parallel_tool_calls: boolean` - Specifies the event type. For a wait action, this property is always set to `wait`. + Whether to enable [parallel function calling](/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `"wait"` + - `required_action: object { submit_tool_outputs, type }` - - `actions: optional BetaComputerActionList` + Details on the action required to continue the run. Will be `null` if no action is required. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `submit_tool_outputs: object { tool_calls }` - - `Click object { button, type, x, 2 more }` + Details on the tool outputs needed for this run to continue. - A click action. + - `tool_calls: array of RequiredActionFunctionToolCall` - - `DoubleClick object { keys, type, x, y }` + A list of the relevant tool calls. - A double click action. + - `id: string` - - `Drag object { path, type, keys }` + 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. - A drag action. + - `function: object { arguments, name }` - - `Keypress object { keys, type }` + The function definition. - A collection of keypresses the model would like to perform. + - `arguments: string` - - `Move object { type, x, y, keys }` + The arguments that the model expects you to pass to the function. - A mouse move action. + - `name: string` - - `Screenshot object { type }` + The name of the function. - A screenshot action. + - `type: "function"` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + The type of tool call the output is required for. For now, this is always `function`. - A scroll action. + - `"function"` - - `Type object { text, type }` + - `type: "submit_tool_outputs"` - An action to type in text. + For now, this is always `submit_tool_outputs`. - - `Wait object { type }` + - `"submit_tool_outputs"` - A wait action. + - `response_format: AssistantResponseFormatOption` - - `agent: optional object { agent_name }` + 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 agent that produced this item. + 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_name: string` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - The canonical name of 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. - - `ComputerCallOutput object { id, call_id, output, 5 more }` + - `"auto"` - - `id: string` + `auto` is the default value - The unique ID of the computer call tool output. + - `"auto"` - - `call_id: string` + - `ResponseFormatText object { type }` - The ID of the computer tool call that produced the output. + Default response format. Used to generate text responses. - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `type: "text"` - A computer screenshot image used with the computer use tool. + The type of response format being defined. Always `text`. - - `type: "computer_screenshot"` + - `"text"` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `ResponseFormatJSONObject object { type }` - - `"computer_screenshot"` + 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 identifier of an uploaded file that contains the screenshot. + The type of response format being defined. Always `json_object`. - - `image_url: optional string` + - `"json_object"` - The URL of the screenshot image. + - `ResponseFormatJSONSchema object { json_schema, type }` - - `status: "completed" or "incomplete" or "failed" or "in_progress"` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `json_schema: object { name, description, schema, strict }` - - `"completed"` + Structured Outputs configuration options, including a JSON Schema. - - `"incomplete"` + - `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. - - `"in_progress"` + - `description: optional string` - - `type: "computer_call_output"` + 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 computer tool call output. Always `computer_call_output`. + - `schema: optional map[unknown]` - - `"computer_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/). - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `strict: optional boolean` - The safety checks reported by the API that have been acknowledged by the - developer. + 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). - - `id: string` + - `type: "json_schema"` - The ID of the pending safety check. + The type of response format being defined. Always `json_schema`. - - `code: optional string` + - `"json_schema"` - The type of the pending safety check. + - `started_at: number` - - `message: optional string` + The Unix timestamp (in seconds) for when the run was started. - Details about the pending safety check. + - `status: "queued" or "in_progress" or "requires_action" or 6 more` - - `agent: optional object { agent_name }` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - The agent that produced this item. + - `"queued"` - - `agent_name: string` + - `"in_progress"` - The canonical name of the agent that produced this item. + - `"requires_action"` - - `created_by: optional string` + - `"cancelling"` - The identifier of the actor that created the item. + - `"cancelled"` - - `WebSearchCall object { id, action, status, 2 more }` + - `"failed"` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `"completed"` - - `id: string` + - `"incomplete"` - The unique ID of the web search tool call. + - `"expired"` - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + - `thread_id: 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). + The ID of the [thread](/docs/api-reference/threads) that was executed on as a part of this run. - - `Search object { type, queries, query, sources }` + - `tool_choice: AssistantToolChoiceOption` - Action type "search" - Performs a web search query. + 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. - - `type: "search"` + - `"none" or "auto" or "required"` - The action type. + `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. - - `"search"` + - `"none"` - - `queries: optional array of string` + - `"auto"` - The search queries. + - `"required"` - - `query: optional string` + - `AssistantToolChoice object { type, function }` - The search query. + Specifies a tool the model should use. Use to force the model to call a specific tool. - - `sources: optional array of object { type, url }` + - `type: "function" or "code_interpreter" or "file_search"` - The sources used in the search. + The type of the tool. If type is `function`, the function name must be set - - `type: "url"` + - `"function"` - The type of source. Always `url`. + - `"code_interpreter"` - - `"url"` + - `"file_search"` - - `url: string` + - `function: optional AssistantToolChoiceFunction` - The URL of the source. + - `name: string` - - `OpenPage object { type, url }` + The name of the function to call. - Action type "open_page" - Opens a specific URL from search results. + - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool` - - `type: "open_page"` + The list of tools that the [assistant](/docs/api-reference/assistants) used for this run. - 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 { id, arguments, call_id, 7 more }` + - `description: optional string` - - `id: string` + A description of what the function does, used by the model to choose when and how to call the function. - The unique ID of the function tool call. + - `parameters: optional FunctionParameters` - - `arguments: 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. - A JSON string of the arguments to pass to the function. + Omitting `parameters` defines a function with an empty parameter list. - - `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 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). - - `name: string` + - `type: "function"` - The name of the function to run. + The type of tool being defined: `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. + - `truncation_strategy: object { type, last_messages }` - - `"in_progress"` + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `"completed"` + - `type: "auto" or "last_messages"` - - `"incomplete"` + 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: "function_call"` + - `"auto"` - The type of the function tool call. Always `function_call`. + - `"last_messages"` - - `"function_call"` + - `last_messages: optional number` - - `agent: optional object { agent_name }` + The number of most recent messages from the thread when constructing the context for the run. - The agent that produced this item. + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - - `agent_name: 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 canonical name of the agent that produced this item. + - `completion_tokens: number` - - `caller: optional object { type } or object { caller_id, type }` + Number of completion tokens used over the course of the run. - The execution context that produced this tool call. + - `prompt_tokens: number` - - `Direct object { type }` + Number of prompt tokens used over the course of the run. - - `type: "direct"` + - `total_tokens: number` - - `"direct"` + Total number of tokens used (prompt + completion). - - `Program object { caller_id, type }` + - `temperature: optional number` - - `caller_id: string` + The sampling temperature used for this run. If not set, defaults to 1. - The call ID of the program item that produced this tool call. + - `top_p: optional number` - - `type: "program"` + The nucleus sampling value used for this run. If not set, defaults to 1. - - `"program"` + - `event: "thread.run.created"` - - `created_by: optional string` + - `"thread.run.created"` - The identifier of the actor that created the item. + - `object { data, event }` - - `namespace: optional string` + Occurs when a [run](/docs/api-reference/runs/object) moves to a `queued` status. - The namespace of the function to run. + - `data: Run` - - `FunctionCallOutput object { id, call_id, output, 5 more }` + Represents an execution run on a [thread](/docs/api-reference/threads). - - `id: string` + - `event: "thread.run.queued"` - The unique ID of the function call tool output. + - `"thread.run.queued"` - - `call_id: string` + - `object { data, event }` - The unique ID of the function tool call generated by the model. + Occurs when a [run](/docs/api-reference/runs/object) moves to an `in_progress` status. - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `data: Run` - The output from the function call generated by your code. - Can be a string or an list of output content. + Represents an execution run on a [thread](/docs/api-reference/threads). - - `StringOutput = string` + - `event: "thread.run.in_progress"` - A string of the output of the function call. + - `"thread.run.in_progress"` - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `object { data, event }` - Text, image, or file output of the function call. + Occurs when a [run](/docs/api-reference/runs/object) moves to a `requires_action` status. - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `data: Run` - A text input to the model. + Represents an execution run on a [thread](/docs/api-reference/threads). - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `event: "thread.run.requires_action"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `"thread.run.requires_action"` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `object { data, event }` - A file input to the model. + Occurs when a [run](/docs/api-reference/runs/object) is completed. - - `status: "in_progress" or "completed" or "incomplete"` + - `data: Run` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Represents an execution run on a [thread](/docs/api-reference/threads). - - `"in_progress"` + - `event: "thread.run.completed"` - - `"completed"` + - `"thread.run.completed"` - - `"incomplete"` + - `object { data, event }` - - `type: "function_call_output"` + Occurs when a [run](/docs/api-reference/runs/object) ends with status `incomplete`. - The type of the function tool call output. Always `function_call_output`. + - `data: Run` - - `"function_call_output"` + Represents an execution run on a [thread](/docs/api-reference/threads). - - `agent: optional object { agent_name }` + - `event: "thread.run.incomplete"` - The agent that produced this item. + - `"thread.run.incomplete"` - - `agent_name: string` + - `object { data, event }` - The canonical name of the agent that produced this item. + Occurs when a [run](/docs/api-reference/runs/object) fails. - - `caller: optional object { type } or object { caller_id, type }` + - `data: Run` - The execution context that produced this tool call. + Represents an execution run on a [thread](/docs/api-reference/threads). - - `Direct object { type }` + - `event: "thread.run.failed"` - - `type: "direct"` + - `"thread.run.failed"` - The caller type. Always `direct`. + - `object { data, event }` - - `"direct"` + Occurs when a [run](/docs/api-reference/runs/object) moves to a `cancelling` status. - - `Program object { caller_id, type }` + - `data: Run` - - `caller_id: string` + Represents an execution run on a [thread](/docs/api-reference/threads). - The call ID of the program item that produced this tool call. + - `event: "thread.run.cancelling"` - - `type: "program"` + - `"thread.run.cancelling"` - The caller type. Always `program`. + - `object { data, event }` - - `"program"` + Occurs when a [run](/docs/api-reference/runs/object) is cancelled. - - `created_by: optional string` + - `data: Run` - The identifier of the actor that created the item. + Represents an execution run on a [thread](/docs/api-reference/threads). - - `AgentMessage object { id, author, content, 3 more }` + - `event: "thread.run.cancelled"` - - `id: string` + - `"thread.run.cancelled"` - The unique ID of the agent message. + - `object { data, event }` - - `author: string` + Occurs when a [run](/docs/api-reference/runs/object) expires. - The sending agent identity. + - `data: Run` - - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` + Represents an execution run on a [thread](/docs/api-reference/threads). - Encrypted content sent between agents. + - `event: "thread.run.expired"` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `"thread.run.expired"` - A text input to the model. +### Thread Stream Event - - `BetaResponseOutputText object { annotations, text, type, logprobs }` +- `ThreadStreamEvent object { data, event, enabled }` - A text output from the model. + Occurs when a new [thread](/docs/api-reference/threads/object) is created. - - `Text object { text, type }` + - `data: Thread` - A text content. + Represents a thread that contains [messages](/docs/api-reference/messages). - - `text: string` + - `id: string` - - `type: "text"` + The identifier, which can be referenced in API endpoints. - - `"text"` + - `created_at: number` - - `SummaryText object { text, type }` + The Unix timestamp (in seconds) for when the thread was created. - A summary text from the model. + - `metadata: Metadata` - - `text: 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. - A summary of the reasoning output from the model so far. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `type: "summary_text"` + - `object: "thread"` - The type of the object. Always `summary_text`. + The object type, which is always `thread`. - - `"summary_text"` + - `"thread"` - - `ReasoningText object { text, type }` + - `tool_resources: object { code_interpreter, file_search }` - Reasoning text from the model. + 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. - - `text: string` + - `code_interpreter: optional object { file_ids }` - The reasoning text from the model. + - `file_ids: optional array of string` - - `type: "reasoning_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. - The type of the reasoning text. Always `reasoning_text`. + - `file_search: optional object { vector_store_ids }` - - `"reasoning_text"` + - `vector_store_ids: optional array of string` - - `BetaResponseOutputRefusal object { refusal, type }` + 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. - A refusal from the model. + - `event: "thread.created"` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `"thread.created"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `enabled: optional boolean` - - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` + Whether to enable input audio transcription. - A screenshot of a computer. +# Threads - - `detail: "low" or "high" or "auto" or "original"` +## Create thread - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. +**post** `/threads` - - `"low"` +Create a thread. - - `"high"` +### Body Parameters - - `"auto"` +- `messages: optional array of object { content, role, attachments, metadata }` - - `"original"` + A list of [messages](/docs/api-reference/messages) to start the thread with. - - `file_id: string` + - `content: string or array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlockParam` - The identifier of an uploaded file that contains the screenshot. + The text contents of the message. - - `image_url: string` + - `TextContent = string` - The URL of the screenshot image. + The text contents of the message. - - `type: "computer_screenshot"` + - `ArrayOfContentParts = array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlockParam` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + 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). - - `"computer_screenshot"` + - `ImageFileContentBlock object { image_file, type }` - - `prompt_cache_breakpoint: optional object { mode }` + References an image [File](/docs/api-reference/files) in the content of a 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. + - `image_file: ImageFile` - - `mode: "explicit"` + - `file_id: string` - The breakpoint mode. Always `explicit`. + 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. - - `"explicit"` + - `detail: optional "auto" or "low" or "high"` - - `BetaResponseInputFile object { type, detail, file_data, 4 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`. - A file input to the model. + - `"auto"` - - `EncryptedContent object { encrypted_content, type }` + - `"low"` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `"high"` - - `encrypted_content: string` + - `type: "image_file"` - Opaque encrypted content. + Always `image_file`. - - `type: "encrypted_content"` + - `"image_file"` - The type of the input item. Always `encrypted_content`. + - `ImageURLContentBlock object { image_url, type }` - - `"encrypted_content"` + References an image URL in the content of a message. - - `recipient: string` + - `image_url: ImageURL` - The destination agent identity. + - `url: string` - - `type: "agent_message"` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - The type of the item. Always `agent_message`. + - `detail: optional "auto" or "low" or "high"` - - `"agent_message"` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - - `agent: optional object { agent_name }` + - `"auto"` - The agent that produced this item. + - `"low"` - - `agent_name: string` + - `"high"` - The canonical name of the agent that produced this item. + - `type: "image_url"` - - `MultiAgentCall object { id, action, arguments, 3 more }` + The type of the content part. - - `id: string` + - `"image_url"` - The unique ID of the multi-agent call item. + - `TextContentBlockParam object { text, type }` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + The text content that is part of a message. - The multi-agent action to execute. + - `text: string` - - `"spawn_agent"` + Text content to be sent to the model - - `"interrupt_agent"` + - `type: "text"` - - `"list_agents"` + Always `text`. - - `"send_message"` + - `"text"` - - `"followup_task"` + - `role: "user" or "assistant"` - - `"wait_agent"` + The role of the entity that is creating the message. Allowed values include: - - `arguments: 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 JSON string of arguments generated for the action. + - `"user"` - - `call_id: string` + - `"assistant"` - The unique ID linking this call to its output. + - `attachments: optional array of object { file_id, tools }` - - `type: "multi_agent_call"` + A list of files attached to the message, and the tools they should be added to. - The type of the multi-agent call. Always `multi_agent_call`. + - `file_id: optional string` - - `"multi_agent_call"` + The ID of the file to attach to the message. - - `agent: optional object { agent_name }` + - `tools: optional array of CodeInterpreterTool or object { type }` - The agent that produced this item. + The tools to add this file to. - - `agent_name: string` + - `CodeInterpreterTool object { type }` - The canonical name of the agent that produced this item. + - `type: "code_interpreter"` - - `MultiAgentCallOutput object { id, action, call_id, 3 more }` + The type of tool being defined: `code_interpreter` - - `id: string` + - `"code_interpreter"` - The unique ID of the multi-agent call output item. + - `FileSearchTool object { type }` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `type: "file_search"` - The multi-agent action that produced this result. + The type of tool being defined: `file_search` - - `"spawn_agent"` + - `"file_search"` - - `"interrupt_agent"` + - `metadata: optional Metadata` - - `"list_agents"` + 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. - - `"send_message"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `"followup_task"` +- `metadata: optional Metadata` - - `"wait_agent"` + 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. - - `call_id: string` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The unique ID of the multi-agent call. +- `tool_resources: optional object { code_interpreter, file_search }` - - `output: array of BetaResponseOutputText` + 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. - Text output returned by the multi-agent action. + - `code_interpreter: optional object { file_ids }` - - `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_ids: optional array of string` - The annotations of the text 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. - - `text: string` + - `file_search: optional object { vector_store_ids, vector_stores }` - The text output from the model. + - `vector_store_ids: optional array of string` - - `type: "output_text"` + 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. - The type of the output text. Always `output_text`. + - `vector_stores: optional array of object { chunking_strategy, file_ids, metadata }` - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + A helper to create a [vector store](/docs/api-reference/vector-stores/object) with file_ids and attach it to this thread. There can be a maximum of 1 vector store attached to the thread. - - `type: "multi_agent_call_output"` + - `chunking_strategy: optional object { type } or object { static, type }` - The type of the multi-agent result. Always `multi_agent_call_output`. + The chunking strategy used to chunk the file(s). If not set, will use the `auto` strategy. - - `"multi_agent_call_output"` + - `AutoChunkingStrategy object { type }` - - `agent: optional object { agent_name }` + The default strategy. This strategy currently uses a `max_chunk_size_tokens` of `800` and `chunk_overlap_tokens` of `400`. - The agent that produced this item. + - `type: "auto"` - - `agent_name: string` + Always `auto`. - The canonical name of the agent that produced this item. + - `"auto"` - - `ToolSearchCall object { id, arguments, call_id, 5 more }` + - `StaticChunkingStrategy object { static, type }` - - `id: string` + - `static: object { chunk_overlap_tokens, max_chunk_size_tokens }` - The unique ID of the tool search call item. + - `chunk_overlap_tokens: number` - - `arguments: unknown` + The number of tokens that overlap between chunks. The default value is `400`. - Arguments used for the tool search call. + Note that the overlap must not exceed half of `max_chunk_size_tokens`. - - `call_id: string` + - `max_chunk_size_tokens: number` - The unique ID of the tool search call generated by the model. + The maximum number of tokens in each chunk. The default value is `800`. The minimum value is `100` and the maximum value is `4096`. - - `execution: "server" or "client"` + - `type: "static"` - Whether tool search was executed by the server or by the client. + Always `static`. - - `"server"` + - `"static"` - - `"client"` + - `file_ids: optional array of string` - - `status: "in_progress" or "completed" or "incomplete"` + 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 status of the tool search call item that was recorded. + - `metadata: optional Metadata` - - `"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. - - `"completed"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `"incomplete"` +### Returns - - `type: "tool_search_call"` +- `Thread object { id, created_at, metadata, 2 more }` - The type of the item. Always `tool_search_call`. + Represents a thread that contains [messages](/docs/api-reference/messages). - - `"tool_search_call"` + - `id: string` - - `agent: optional object { agent_name }` + The identifier, which can be referenced in API endpoints. - The agent that produced this item. + - `created_at: number` - - `agent_name: string` + The Unix timestamp (in seconds) for when the thread was created. - The canonical name of the agent that produced this item. + - `metadata: Metadata` - - `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. - The identifier of the actor that created the item. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `ToolSearchOutput object { id, call_id, execution, 5 more }` + - `object: "thread"` - - `id: string` + The object type, which is always `thread`. - The unique ID of the tool search output item. + - `"thread"` - - `call_id: string` + - `tool_resources: object { code_interpreter, file_search }` - The unique ID of the tool search call generated by the model. + 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. - - `execution: "server" or "client"` + - `code_interpreter: optional object { file_ids }` - Whether tool search was executed by the server or by the client. + - `file_ids: optional array of string` - - `"server"` + 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. - - `"client"` + - `file_search: optional object { vector_store_ids }` - - `status: "in_progress" or "completed" or "incomplete"` + - `vector_store_ids: optional array of string` - The status of the tool search output item that was recorded. + 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. - - `"in_progress"` +### Example - - `"completed"` +```http +curl https://api.openai.com/v1/threads \ + -X POST \ + -H 'OpenAI-Beta: assistants=v2' \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - - `"incomplete"` +#### Response - - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` +```json +{ + "id": "id", + "created_at": 0, + "metadata": { + "foo": "string" + }, + "object": "thread", + "tool_resources": { + "code_interpreter": { + "file_ids": [ + "string" + ] + }, + "file_search": { + "vector_store_ids": [ + "string" + ] + } + } +} +``` - The loaded tool definitions returned by tool search. +### Empty - - `Function object { name, parameters, strict, 5 more }` +```http +curl https://api.openai.com/v1/threads \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "OpenAI-Beta: assistants=v2" \ + -d '' +``` - 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 - - `name: string` +```json +{ + "id": "thread_abc123", + "object": "thread", + "created_at": 1699012949, + "metadata": {}, + "tool_resources": {} +} +``` - The name of the function to call. +### Messages - - `parameters: map[unknown]` +```http +curl https://api.openai.com/v1/threads \ +-H "Content-Type: application/json" \ +-H "Authorization: Bearer $OPENAI_API_KEY" \ +-H "OpenAI-Beta: assistants=v2" \ +-d '{ + "messages": [{ + "role": "user", + "content": "Hello, what is AI?" + }, { + "role": "user", + "content": "How does AI work? Explain it in simple terms." + }] + }' +``` - A JSON schema object describing the parameters of the function. +#### Response - - `strict: boolean` +```json +{ + "id": "thread_abc123", + "object": "thread", + "created_at": 1699014083, + "metadata": {}, + "tool_resources": {} +} +``` - Whether strict parameter validation is enforced for this function tool. +## Create thread and run - - `type: "function"` +**post** `/threads/runs` - The type of the function tool. Always `function`. +Create a thread and run it in one request. - - `"function"` +### Body Parameters - - `allowed_callers: optional array of "direct" or "programmatic"` +- `assistant_id: string` - The tool invocation context(s). + The ID of the [assistant](/docs/api-reference/assistants) to use to execute this run. - - `"direct"` +- `instructions: optional string` - - `"programmatic"` + Override the default system message of the assistant. This is useful for modifying the behavior on a per-run basis. - - `defer_loading: optional boolean` +- `max_completion_tokens: optional number` - Whether this function is deferred and loaded via tool search. + 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. - - `description: optional string` +- `max_prompt_tokens: optional number` - A description of the function. Used by the model to determine whether or not to call the function. + 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. - - `output_schema: optional map[unknown]` +- `metadata: optional Metadata` - A JSON schema object describing the JSON value encoded in string outputs for this 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. - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - 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). +- `model: optional string or "gpt-5" or "gpt-5-mini" or "gpt-5-nano" or 35 more` - - `type: "file_search"` + 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 type of the file search tool. Always `file_search`. + - `string` - - `"file_search"` + - `"gpt-5" or "gpt-5-mini" or "gpt-5-nano" or 35 more` - - `vector_store_ids: array of 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 IDs of the vector stores to search. + - `"gpt-5"` - - `filters: optional object { key, type, value } or object { filters, type }` + - `"gpt-5-mini"` - A filter to apply. + - `"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-4.1"` - - `type: "eq" or "ne" or "gt" or 5 more` + - `"gpt-4.1-mini"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `"gpt-4.1-nano"` - - `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-2025-04-14"` - - `"eq"` + - `"gpt-4.1-mini-2025-04-14"` - - `"ne"` + - `"gpt-4.1-nano-2025-04-14"` - - `"gt"` + - `"gpt-4o"` - - `"gte"` + - `"gpt-4o-2024-11-20"` - - `"lt"` + - `"gpt-4o-2024-08-06"` - - `"lte"` + - `"gpt-4o-2024-05-13"` - - `"in"` + - `"gpt-4o-mini"` - - `"nin"` + - `"gpt-4o-mini-2024-07-18"` - - `value: string or number or boolean or array of string or number` + - `"gpt-4.5-preview"` - The value to compare against the attribute key; supports string, number, or boolean types. + - `"gpt-4.5-preview-2025-02-27"` - - `string` + - `"gpt-4-turbo"` - - `number` + - `"gpt-4-turbo-2024-04-09"` - - `boolean` + - `"gpt-4-0125-preview"` - - `array of string or number` + - `"gpt-4-turbo-preview"` - - `string` + - `"gpt-4-1106-preview"` - - `number` + - `"gpt-4-vision-preview"` - - `CompoundFilter object { filters, type }` + - `"gpt-4"` - Combine multiple filters using `and` or `or`. + - `"gpt-4-0314"` - - `filters: array of object { key, type, value } or unknown` + - `"gpt-4-0613"` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `"gpt-4-32k"` - - `ComparisonFilter object { key, type, value }` + - `"gpt-4-32k-0314"` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `"gpt-4-32k-0613"` - - `key: string` + - `"gpt-3.5-turbo"` - The key to compare against the value. + - `"gpt-3.5-turbo-16k"` - - `type: "eq" or "ne" or "gt" or 5 more` + - `"gpt-3.5-turbo-0613"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `"gpt-3.5-turbo-1106"` - - `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-3.5-turbo-0125"` - - `"eq"` + - `"gpt-3.5-turbo-16k-0613"` - - `"ne"` +- `parallel_tool_calls: optional boolean` - - `"gt"` + Whether to enable [parallel function calling](/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `"gte"` +- `response_format: optional AssistantResponseFormatOption` - - `"lt"` + 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`. - - `"lte"` + 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). - - `"in"` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `"nin"` + **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. - - `value: string or number or boolean or array of string or number` + - `"auto"` - The value to compare against the attribute key; supports string, number, or boolean types. + `auto` is the default value - - `string` + - `"auto"` - - `number` + - `ResponseFormatText object { type }` - - `boolean` + Default response format. Used to generate text responses. - - `array of string or number` + - `type: "text"` - - `string` + The type of response format being defined. Always `text`. - - `number` + - `"text"` - - `unknown` + - `ResponseFormatJSONObject object { type }` - - `type: "and" or "or"` + 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 of operation: `and` or `or`. + - `type: "json_object"` - - `"and"` + The type of response format being defined. Always `json_object`. - - `"or"` + - `"json_object"` - - `max_num_results: optional number` + - `ResponseFormatJSONSchema object { json_schema, type }` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `json_schema: object { name, description, schema, strict }` - Ranking options for search. + Structured Outputs configuration options, including a JSON Schema. - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `name: string` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + 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. - - `embedding_weight: number` + - `description: optional string` - The weight of the embedding in the reciprocal ranking fusion. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `text_weight: number` + - `schema: optional map[unknown]` - The weight of the text in the reciprocal ranking fusion. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `ranker: optional "auto" or "default-2024-11-15"` + - `strict: optional boolean` - The ranker to use for the 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). - - `"auto"` + - `type: "json_schema"` - - `"default-2024-11-15"` + The type of response format being defined. Always `json_schema`. - - `score_threshold: optional number` + - `"json_schema"` - 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. +- `stream: optional boolean` - - `Computer object { type }` + 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. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). +- `temperature: optional number` - - `type: "computer"` + 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 type of the computer tool. Always `computer`. +- `thread: optional object { messages, metadata, tool_resources }` - - `"computer"` + Options to create a new thread. If no thread is provided when running a + request, an empty thread will be created. - - `ComputerUsePreview object { display_height, display_width, environment, type }` + - `messages: optional array of object { content, role, attachments, metadata }` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + A list of [messages](/docs/api-reference/messages) to start the thread with. - - `display_height: number` + - `content: string or array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlockParam` - The height of the computer display. + The text contents of the message. - - `display_width: number` + - `TextContent = string` - The width of the computer display. + The text contents of the message. - - `environment: "windows" or "mac" or "linux" or 2 more` + - `ArrayOfContentParts = array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlockParam` - The type of computer environment to control. + 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). - - `"windows"` + - `ImageFileContentBlock object { image_file, type }` - - `"mac"` + References an image [File](/docs/api-reference/files) in the content of a message. - - `"linux"` + - `image_file: ImageFile` - - `"ubuntu"` + - `file_id: string` - - `"browser"` + 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. - - `type: "computer_use_preview"` + - `detail: optional "auto" or "low" or "high"` - The type of the computer use tool. Always `computer_use_preview`. + 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`. - - `"computer_use_preview"` + - `"auto"` - - `WebSearch object { type, filters, search_context_size, user_location }` + - `"low"` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `"high"` - - `type: "web_search" or "web_search_2025_08_26"` + - `type: "image_file"` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + Always `image_file`. - - `"web_search"` + - `"image_file"` - - `"web_search_2025_08_26"` + - `ImageURLContentBlock object { image_url, type }` - - `filters: optional object { allowed_domains }` + References an image URL in the content of a message. - Filters for the search. + - `image_url: ImageURL` - - `allowed_domains: optional array of string` + - `url: string` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `detail: optional "auto" or "low" or "high"` - - `search_context_size: optional "low" or "medium" or "high"` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `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. + - `"auto"` - `"low"` - - `"medium"` - - `"high"` - - `user_location: optional object { city, country, region, 2 more }` + - `type: "image_url"` - The approximate location of the user. + The type of the content part. - - `city: optional string` + - `"image_url"` - Free text input for the city of the user, e.g. `San Francisco`. + - `TextContentBlockParam object { text, type }` - - `country: optional string` + The text content that is part of a message. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `text: string` - - `region: optional string` + Text content to be sent to the model - Free text input for the region of the user, e.g. `California`. + - `type: "text"` - - `timezone: optional string` + Always `text`. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `"text"` - - `type: optional "approximate"` + - `role: "user" or "assistant"` - The type of location approximation. Always `approximate`. + The role of the entity that is creating the message. Allowed values include: - - `"approximate"` + - `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. - - `Mcp object { server_label, type, allowed_callers, 9 more }` + - `"user"` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `"assistant"` - - `server_label: string` + - `attachments: optional array of object { file_id, tools }` - A label for this MCP server, used to identify it in tool calls. + A list of files attached to the message, and the tools they should be added to. - - `type: "mcp"` + - `file_id: optional string` - The type of the MCP tool. Always `mcp`. + The ID of the file to attach to the message. - - `"mcp"` + - `tools: optional array of CodeInterpreterTool or object { type }` - - `allowed_callers: optional array of "direct" or "programmatic"` + The tools to add this file to. - The tool invocation context(s). + - `CodeInterpreterTool object { type }` - - `"direct"` + - `type: "code_interpreter"` - - `"programmatic"` + The type of tool being defined: `code_interpreter` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + - `"code_interpreter"` - List of allowed tool names or a filter object. + - `FileSearchTool object { type }` - - `McpAllowedTools = array of string` + - `type: "file_search"` - A string array of allowed tool names + The type of tool being defined: `file_search` - - `McpToolFilter object { read_only, tool_names }` + - `"file_search"` - A filter object to specify which tools are allowed. + - `metadata: optional Metadata` - - `read_only: optional 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. - 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. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `tool_names: optional array of string` + - `metadata: optional Metadata` - 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. - - `authorization: optional string` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - 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. + - `tool_resources: optional object { code_interpreter, file_search }` - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + 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. - 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + - `code_interpreter: optional object { file_ids }` - Currently supported `connector_id` values are: + - `file_ids: optional array of 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 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. - - `"connector_dropbox"` + - `file_search: optional object { vector_store_ids, vector_stores }` - - `"connector_gmail"` + - `vector_store_ids: optional array of string` - - `"connector_googlecalendar"` + 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. - - `"connector_googledrive"` + - `vector_stores: optional array of object { chunking_strategy, file_ids, metadata }` - - `"connector_microsoftteams"` + A helper to create a [vector store](/docs/api-reference/vector-stores/object) with file_ids and attach it to this thread. There can be a maximum of 1 vector store attached to the thread. - - `"connector_outlookcalendar"` + - `chunking_strategy: optional object { type } or object { static, type }` - - `"connector_outlookemail"` + The chunking strategy used to chunk the file(s). If not set, will use the `auto` strategy. - - `"connector_sharepoint"` + - `AutoChunkingStrategy object { type }` - - `defer_loading: optional boolean` + The default strategy. This strategy currently uses a `max_chunk_size_tokens` of `800` and `chunk_overlap_tokens` of `400`. - Whether this MCP tool is deferred and discovered via tool search. + - `type: "auto"` - - `headers: optional map[string]` + Always `auto`. - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `"auto"` - - `require_approval: optional object { always, never } or "always" or "never"` + - `StaticChunkingStrategy object { static, type }` - Specify which of the MCP server's tools require approval. + - `static: object { chunk_overlap_tokens, max_chunk_size_tokens }` - - `McpToolApprovalFilter object { always, never }` + - `chunk_overlap_tokens: 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 number of tokens that overlap between chunks. The default value is `400`. - - `always: optional object { read_only, tool_names }` + Note that the overlap must not exceed half of `max_chunk_size_tokens`. - A filter object to specify which tools are allowed. + - `max_chunk_size_tokens: number` - - `read_only: optional boolean` + The maximum number of tokens in each chunk. The default value is `800`. The minimum value is `100` and the maximum value is `4096`. - 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: "static"` - - `tool_names: optional array of string` + Always `static`. - List of allowed tool names. + - `"static"` - - `never: optional object { read_only, tool_names }` + - `file_ids: optional array of string` - A filter object to specify which tools are allowed. + 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. - - `read_only: optional boolean` + - `metadata: optional Metadata` - 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. + 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. - - `tool_names: optional array of string` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - List of allowed tool names. +- `tool_choice: optional AssistantToolChoiceOption` - - `McpToolApprovalSetting = "always" or "never"` + 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. - 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" or "auto" or "required"` - - `"always"` + `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. - - `"never"` + - `"none"` - - `server_description: optional string` + - `"auto"` - Optional description of the MCP server, used to provide more context. + - `"required"` - - `server_url: optional string` + - `AssistantToolChoice object { type, function }` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + Specifies a tool the model should use. Use to force the model to call a specific tool. - - `tunnel_id: optional string` + - `type: "function" or "code_interpreter" or "file_search"` - 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 tool. If type is `function`, the function name must be set - - `CodeInterpreter object { container, type, allowed_callers }` + - `"function"` - A tool that runs Python code to help generate a response to a prompt. + - `"code_interpreter"` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + - `"file_search"` - 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. + - `function: optional AssistantToolChoiceFunction` - - `string` + - `name: string` - The container ID. + The name of the function to call. - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` +- `tool_resources: optional object { code_interpreter, file_search }` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + 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: "auto"` + - `code_interpreter: optional object { file_ids }` - Always `auto`. + - `file_ids: optional array of string` - - `"auto"` + 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. - - `file_ids: optional array of string` + - `file_search: optional object { vector_store_ids }` - An optional list of uploaded files to make available to your code. + - `vector_store_ids: optional array of string` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + 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 memory limit for the code interpreter container. +- `tools: optional array of CodeInterpreterTool or FileSearchTool or FunctionTool` - - `"1g"` + Override the tools the assistant can use for this run. This is useful for modifying the behavior on a per-run basis. - - `"4g"` + - `CodeInterpreterTool object { type }` - - `"16g"` + - `FileSearchTool object { type, file_search }` - - `"64g"` + - `type: "file_search"` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + The type of tool being defined: `file_search` - Network access policy for the container. + - `"file_search"` - - `BetaContainerNetworkPolicyDisabled object { type }` + - `file_search: optional object { max_num_results, ranking_options }` - - `type: "disabled"` + Overrides for the file search tool. - Disable outbound network access. Always `disabled`. + - `max_num_results: optional number` - - `"disabled"` + 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. - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + 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. - - `allowed_domains: array of string` + - `ranking_options: optional object { score_threshold, ranker }` - A list of allowed domains when type is `allowlist`. + 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: "allowlist"` + See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - Allow outbound network access only to specified domains. Always `allowlist`. + - `score_threshold: number` - - `"allowlist"` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` + - `ranker: optional "auto" or "default_2024_08_21"` - Optional domain-scoped secrets for allowlisted domains. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `domain: string` + - `"auto"` - The domain associated with the secret. + - `"default_2024_08_21"` + + - `FunctionTool object { function, type }` + + - `function: FunctionDefinition` - `name: string` - The name of the secret to inject for the domain. + 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. - - `value: string` + - `description: optional string` - The secret value to inject for the domain. + A description of what the function does, used by the model to choose when and how to call the function. - - `type: "code_interpreter"` + - `parameters: optional FunctionParameters` - The type of the code interpreter tool. Always `code_interpreter`. + 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. - - `"code_interpreter"` + Omitting `parameters` defines a function with an empty parameter list. - - `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 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). - - `"direct"` + - `type: "function"` - - `"programmatic"` + The type of tool being defined: `function` - - `ProgrammaticToolCalling object { type }` + - `"function"` - - `type: "programmatic_tool_calling"` +- `top_p: optional number` - The type of the tool. Always `programmatic_tool_calling`. + 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. - - `"programmatic_tool_calling"` + We generally recommend altering this or temperature but not both. - - `ImageGeneration object { type, action, background, 9 more }` +- `truncation_strategy: optional object { type, last_messages }` - A tool that generates images using the GPT image models. + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `type: "image_generation"` + - `type: "auto" or "last_messages"` - The type of the image generation tool. Always `image_generation`. + 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`. - - `"image_generation"` + - `"auto"` - - `action: optional "generate" or "edit" or "auto"` + - `"last_messages"` - Whether to generate a new image or edit an existing image. Default: `auto`. + - `last_messages: optional number` - - `"generate"` + The number of most recent messages from the thread when constructing the context for the run. - - `"edit"` +### Returns - - `"auto"` +- `Run object { id, assistant_id, cancelled_at, 24 more }` - - `background: optional "transparent" or "opaque" or "auto"` + Represents an execution run on a [thread](/docs/api-reference/threads). - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + - `id: string` - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + The identifier, which can be referenced in API endpoints. - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `assistant_id: string` - - `"transparent"` + The ID of the [assistant](/docs/api-reference/assistants) used for execution of this run. - - `"opaque"` + - `cancelled_at: number` - - `"auto"` + The Unix timestamp (in seconds) for when the run was cancelled. - - `input_fidelity: optional "high" or "low"` + - `completed_at: number` - 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 Unix timestamp (in seconds) for when the run was completed. - - `"high"` + - `created_at: number` - - `"low"` + The Unix timestamp (in seconds) for when the run was created. - - `input_image_mask: optional object { file_id, image_url }` + - `expires_at: number` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + The Unix timestamp (in seconds) for when the run will expire. - - `file_id: optional string` + - `failed_at: number` - File ID for the mask image. + The Unix timestamp (in seconds) for when the run failed. - - `image_url: optional string` + - `incomplete_details: object { reason }` - Base64-encoded mask image. + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` - The image generation model to use. Default: `gpt-image-1`. + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - - `string` + - `"max_completion_tokens"` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `"max_prompt_tokens"` - The image generation model to use. Default: `gpt-image-1`. + - `instructions: string` - - `"gpt-image-1"` + The instructions that the [assistant](/docs/api-reference/assistants) used for this run. - - `"gpt-image-1-mini"` + - `last_error: object { code, message }` - - `"gpt-image-2"` + The last error associated with this run. Will be `null` if there are no errors. - - `"gpt-image-2-2026-04-21"` + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` - - `"gpt-image-1.5"` + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - - `"chatgpt-image-latest"` + - `"server_error"` - - `moderation: optional "auto" or "low"` + - `"rate_limit_exceeded"` - Moderation level for the generated image. Default: `auto`. + - `"invalid_prompt"` - - `"auto"` + - `message: string` - - `"low"` + A human-readable description of the error. - - `output_compression: optional number` + - `max_completion_tokens: number` - Compression level for the output image. Default: 100. + The maximum number of completion tokens specified to have been used over the course of the run. - - `output_format: optional "png" or "webp" or "jpeg"` + - `max_prompt_tokens: number` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + The maximum number of prompt tokens specified to have been used over the course of the run. - - `"png"` + - `metadata: Metadata` - - `"webp"` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `"jpeg"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `partial_images: optional number` + - `model: string` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + The model that the [assistant](/docs/api-reference/assistants) used for this run. - - `quality: optional "low" or "medium" or "high" or "auto"` + - `object: "thread.run"` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + The object type, which is always `thread.run`. - - `"low"` + - `"thread.run"` - - `"medium"` + - `parallel_tool_calls: boolean` - - `"high"` + Whether to enable [parallel function calling](/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `"auto"` + - `required_action: object { submit_tool_outputs, type }` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + Details on the action required to continue the run. Will be `null` if no action is required. - 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`. + - `submit_tool_outputs: object { tool_calls }` - - `string` + Details on the tool outputs needed for this run to continue. - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `tool_calls: array of RequiredActionFunctionToolCall` - 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 list of the relevant tool calls. - - `"1024x1024"` + - `id: string` - - `"1024x1536"` + 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. - - `"1536x1024"` + - `function: object { arguments, name }` - - `"auto"` + The function definition. - - `LocalShell object { type }` + - `arguments: string` - A tool that allows the model to execute shell commands in a local environment. + The arguments that the model expects you to pass to the function. - - `type: "local_shell"` + - `name: string` - The type of the local shell tool. Always `local_shell`. + The name of the function. - - `"local_shell"` + - `type: "function"` - - `Shell object { type, allowed_callers, environment }` + The type of tool call the output is required for. For now, this is always `function`. - A tool that allows the model to execute shell commands. + - `"function"` - - `type: "shell"` + - `type: "submit_tool_outputs"` - The type of the shell tool. Always `shell`. + For now, this is always `submit_tool_outputs`. - - `"shell"` + - `"submit_tool_outputs"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `response_format: 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. - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + **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. - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `"auto"` - - `type: "container_auto"` + `auto` is the default value - Automatically creates a container for this request + - `"auto"` - - `"container_auto"` + - `ResponseFormatText object { type }` - - `file_ids: optional array of string` + Default response format. Used to generate text responses. - An optional list of uploaded files to make available to your code. + - `type: "text"` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + The type of response format being defined. Always `text`. - The memory limit for the container. + - `"text"` - - `"1g"` + - `ResponseFormatJSONObject object { type }` - - `"4g"` + 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. - - `"16g"` + - `type: "json_object"` - - `"64g"` + The type of response format being defined. Always `json_object`. - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `"json_object"` - Network access policy for the container. + - `ResponseFormatJSONSchema object { json_schema, type }` - - `BetaContainerNetworkPolicyDisabled object { type }` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `json_schema: object { name, description, schema, strict }` - - `skills: optional array of BetaSkillReference or BetaInlineSkill` + Structured Outputs configuration options, including a JSON Schema. - An optional list of skills referenced by id or inline data. + - `name: string` - - `BetaSkillReference object { skill_id, type, version }` + 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. - - `skill_id: string` + - `description: optional string` - The ID of the referenced skill. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `type: "skill_reference"` + - `schema: optional 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"` + - `strict: optional boolean` - - `version: optional 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). - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `type: "json_schema"` - - `BetaInlineSkill object { description, name, source, type }` + The type of response format being defined. Always `json_schema`. - - `description: string` + - `"json_schema"` - The description of the skill. + - `started_at: number` - - `name: string` + The Unix timestamp (in seconds) for when the run was started. - The name of the skill. + - `status: "queued" or "in_progress" or "requires_action" or 6 more` - - `source: BetaInlineSkillSource` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - Inline skill payload + - `"queued"` - - `data: string` + - `"in_progress"` - Base64-encoded skill zip bundle. + - `"requires_action"` - - `media_type: "application/zip"` + - `"cancelling"` - The media type of the inline skill payload. Must be `application/zip`. + - `"cancelled"` - - `"application/zip"` + - `"failed"` - - `type: "base64"` + - `"completed"` - The type of the inline skill source. Must be `base64`. + - `"incomplete"` - - `"base64"` + - `"expired"` - - `type: "inline"` + - `thread_id: string` - Defines an inline skill for this request. + The ID of the [thread](/docs/api-reference/threads) that was executed on as a part of this run. - - `"inline"` + - `tool_choice: AssistantToolChoiceOption` - - `BetaLocalEnvironment object { type, skills }` + 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. - - `type: "local"` + - `"none" or "auto" or "required"` - Use a local computer environment. + `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. - - `"local"` + - `"none"` - - `skills: optional array of BetaLocalSkill` + - `"auto"` - An optional list of skills. + - `"required"` - - `description: string` + - `AssistantToolChoice object { type, function }` - The description of the skill. + Specifies a tool the model should use. Use to force the model to call a specific tool. - - `name: string` + - `type: "function" or "code_interpreter" or "file_search"` - The name of the skill. + The type of the tool. If type is `function`, the function name must be set - - `path: string` + - `"function"` - The path to the directory containing the skill. + - `"code_interpreter"` - - `BetaContainerReference object { container_id, type }` + - `"file_search"` - - `container_id: string` + - `function: optional AssistantToolChoiceFunction` - The ID of the referenced container. + - `name: string` - - `type: "container_reference"` + The name of the function to call. - References a container created with the /v1/containers endpoint + - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool` - - `"container_reference"` + The list of tools that the [assistant](/docs/api-reference/assistants) used for this run. - - `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](https://platform.openai.com/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. + + 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. + + - `ranking_options: optional object { score_threshold, ranker }` - Whether this tool should be deferred and discovered via tool search. + 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. - - `description: optional string` + See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - Optional description of the custom tool, used to provide more context. + - `score_threshold: number` - - `format: optional object { type } or object { definition, syntax, type }` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - The input format for the custom tool. Default is unconstrained text. + - `ranker: optional "auto" or "default_2024_08_21"` - - `Text object { type }` + The ranker to use for the file search. If not specified will use the `auto` ranker. - Unconstrained free-form text. + - `"auto"` - - `type: "text"` + - `"default_2024_08_21"` - Unconstrained text format. Always `text`. + - `FunctionTool object { function, type }` - - `"text"` + - `function: FunctionDefinition` - - `Grammar object { definition, syntax, type }` + - `name: string` - A grammar defined by the user. + 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. - - `definition: string` + - `description: optional string` - The grammar definition. + A description of what the function does, used by the model to choose when and how to call the function. - - `syntax: "lark" or "regex"` + - `parameters: optional FunctionParameters` - The syntax of the grammar definition. One of `lark` or `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. - - `"lark"` + Omitting `parameters` defines a function with an empty parameter list. - - `"regex"` + - `strict: optional boolean` - - `type: "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). - Grammar format. Always `grammar`. + - `type: "function"` - - `"grammar"` + The type of tool being defined: `function` - - `Namespace object { description, name, tools, type }` + - `"function"` - Groups function/custom tools under a shared namespace. + - `truncation_strategy: object { type, last_messages }` - - `description: string` + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - A description of the namespace shown to the model. + - `type: "auto" or "last_messages"` - - `name: string` + 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 namespace name used in tool calls (for example, `crm`). + - `"auto"` - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + - `"last_messages"` - The function/custom tools available inside this namespace. + - `last_messages: optional number` - - `Function object { name, type, allowed_callers, 5 more }` + The number of most recent messages from the thread when constructing the context for the run. - - `name: string` + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - - `type: "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.). - - `"function"` + - `completion_tokens: number` - - `allowed_callers: optional array of "direct" or "programmatic"` + Number of completion tokens used over the course of the run. - The tool invocation context(s). + - `prompt_tokens: number` - - `"direct"` + Number of prompt tokens used over the course of the run. - - `"programmatic"` + - `total_tokens: number` - - `defer_loading: optional boolean` + Total number of tokens used (prompt + completion). - Whether this function should be deferred and discovered via tool search. + - `temperature: optional number` - - `description: optional string` + The sampling temperature used for this run. If not set, defaults to 1. - - `output_schema: optional map[unknown]` + - `top_p: optional number` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + The nucleus sampling value used for this run. If not set, defaults to 1. - - `parameters: optional unknown` +### Example - - `strict: optional boolean` +```http +curl https://api.openai.com/v1/threads/runs \ + -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 + }' +``` - 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. +#### Response - - `Custom object { name, type, allowed_callers, 3 more }` +```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 +} +``` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) +### Example - - `name: string` +```http +curl https://api.openai.com/v1/threads/runs \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" \ + -d '{ + "assistant_id": "asst_abc123", + "thread": { + "messages": [ + {"role": "user", "content": "Explain deep learning to a 5 year old."} + ] + } + }' +``` - The name of the custom tool, used to identify it in tool calls. +#### Response - - `type: "custom"` +```json +{ + "id": "run_abc123", + "object": "thread.run", + "created_at": 1699076792, + "assistant_id": "asst_abc123", + "thread_id": "thread_abc123", + "status": "queued", + "started_at": null, + "expires_at": 1699077392, + "cancelled_at": null, + "failed_at": null, + "completed_at": null, + "required_action": null, + "last_error": null, + "model": "gpt-4o", + "instructions": "You are a helpful assistant.", + "tools": [], + "tool_resources": {}, + "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 type of the custom tool. Always `custom`. +### Streaming - - `"custom"` +```http +curl https://api.openai.com/v1/threads/runs \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" \ + -d '{ + "assistant_id": "asst_123", + "thread": { + "messages": [ + {"role": "user", "content": "Hello"} + ] + }, + "stream": true + }' +``` - - `allowed_callers: optional array of "direct" or "programmatic"` +#### Response - The tool invocation context(s). +```json +event: thread.created +data: {"id":"thread_123","object":"thread","created_at":1710348075,"metadata":{}} - - `"direct"` +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":[],"tool_resources":{},"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} - - `"programmatic"` +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":[],"tool_resources":{},"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} - - `defer_loading: optional boolean` +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":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":[],"tool_resources":{},"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} - Whether this tool should be deferred and discovered via tool search. +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} - - `description: optional string` +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} - Optional description of the custom tool, used to provide more context. +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":{}} - - `format: optional object { type } or object { definition, syntax, type }` +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":{}} - The input format for the custom tool. Default is unconstrained text. +event: thread.message.delta +data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"Hello","annotations":[]}}]}} - - `Text object { type }` +... - Unconstrained free-form text. +event: thread.message.delta +data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" today"}}]}} - - `type: "text"` +event: thread.message.delta +data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"?"}}]}} - Unconstrained text format. Always `text`. +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":{}} - - `"text"` +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}} - - `Grammar object { definition, syntax, type }` +event: thread.run.completed +{"id":"run_123","object":"thread.run","created_at":1710348076,"assistant_id":"asst_123","thread_id":"thread_123","status":"completed","started_at":1713226836,"expires_at":null,"cancelled_at":null,"failed_at":null,"completed_at":1713226837,"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":345,"completion_tokens":11,"total_tokens":356},"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true} - A grammar defined by the user. +event: done +data: [DONE] +``` - - `definition: string` +### Streaming with Functions - The grammar definition. +```http +curl https://api.openai.com/v1/threads/runs \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" \ + -d '{ + "assistant_id": "asst_abc123", + "thread": { + "messages": [ + {"role": "user", "content": "What is the weather like in San Francisco?"} + ] + }, + "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 + }' +``` - - `syntax: "lark" or "regex"` +#### Response - The syntax of the grammar definition. One of `lark` or `regex`. +```json +event: thread.created +data: {"id":"thread_123","object":"thread","created_at":1710351818,"metadata":{}} - - `"lark"` +event: thread.run.created +data: {"id":"run_123","object":"thread.run","created_at":1710351818,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710352418,"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}} - - `"regex"` +event: thread.run.queued +data: {"id":"run_123","object":"thread.run","created_at":1710351818,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710352418,"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}} - - `type: "grammar"` +event: thread.run.in_progress +data: {"id":"run_123","object":"thread.run","created_at":1710351818,"assistant_id":"asst_123","thread_id":"thread_123","status":"in_progress","started_at":1710351818,"expires_at":1710352418,"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}} - Grammar format. Always `grammar`. +event: thread.run.step.created +data: {"id":"step_001","object":"thread.run.step","created_at":1710351819,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"tool_calls","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710352418,"failed_at":null,"last_error":null,"step_details":{"type":"tool_calls","tool_calls":[]},"usage":null} - - `"grammar"` +event: thread.run.step.in_progress +data: {"id":"step_001","object":"thread.run.step","created_at":1710351819,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"tool_calls","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710352418,"failed_at":null,"last_error":null,"step_details":{"type":"tool_calls","tool_calls":[]},"usage":null} - - `type: "namespace"` +event: thread.run.step.delta +data: {"id":"step_001","object":"thread.run.step.delta","delta":{"step_details":{"type":"tool_calls","tool_calls":[{"index":0,"id":"call_XXNp8YGaFrjrSjgqxtC8JJ1B","type":"function","function":{"name":"get_current_weather","arguments":"","output":null}}]}}} - The type of the tool. Always `namespace`. +event: thread.run.step.delta +data: {"id":"step_001","object":"thread.run.step.delta","delta":{"step_details":{"type":"tool_calls","tool_calls":[{"index":0,"type":"function","function":{"arguments":"{\""}}]}}} - - `"namespace"` +event: thread.run.step.delta +data: {"id":"step_001","object":"thread.run.step.delta","delta":{"step_details":{"type":"tool_calls","tool_calls":[{"index":0,"type":"function","function":{"arguments":"location"}}]}}} - - `ToolSearch object { type, description, execution, parameters }` +... - Hosted or BYOT tool search configuration for deferred tools. +event: thread.run.step.delta +data: {"id":"step_001","object":"thread.run.step.delta","delta":{"step_details":{"type":"tool_calls","tool_calls":[{"index":0,"type":"function","function":{"arguments":"ahrenheit"}}]}}} - - `type: "tool_search"` +event: thread.run.step.delta +data: {"id":"step_001","object":"thread.run.step.delta","delta":{"step_details":{"type":"tool_calls","tool_calls":[{"index":0,"type":"function","function":{"arguments":"\"}"}}]}}} - The type of the tool. Always `tool_search`. +event: thread.run.requires_action +data: {"id":"run_123","object":"thread.run","created_at":1710351818,"assistant_id":"asst_123","thread_id":"thread_123","status":"requires_action","started_at":1710351818,"expires_at":1710352418,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":{"type":"submit_tool_outputs","submit_tool_outputs":{"tool_calls":[{"id":"call_XXNp8YGaFrjrSjgqxtC8JJ1B","type":"function","function":{"name":"get_current_weather","arguments":"{\"location\":\"San Francisco, CA\",\"unit\":\"fahrenheit\"}"}}]}},"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":345,"completion_tokens":11,"total_tokens":356},"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} - - `"tool_search"` +event: done +data: [DONE] +``` - - `description: optional string` +## Retrieve thread - Description shown to the model for a client-executed tool search tool. +**get** `/threads/{thread_id}` - - `execution: optional "server" or "client"` +Retrieves a thread. - Whether tool search is executed by the server or by the client. +### Path Parameters - - `"server"` +- `thread_id: string` - - `"client"` +### Returns - - `parameters: optional unknown` +- `Thread object { id, created_at, metadata, 2 more }` - Parameter schema for a client-executed tool search tool. + Represents a thread that contains [messages](/docs/api-reference/messages). - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + - `id: string` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The identifier, which can be referenced in API endpoints. - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `created_at: number` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + The Unix timestamp (in seconds) for when the thread was created. - - `"web_search_preview"` + - `metadata: Metadata` - - `"web_search_preview_2025_03_11"` + 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. - - `search_content_types: optional array of "text" or "image"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `"text"` + - `object: "thread"` - - `"image"` + The object type, which is always `thread`. - - `search_context_size: optional "low" or "medium" or "high"` + - `"thread"` - 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. + - `tool_resources: object { code_interpreter, file_search }` - - `"low"` + 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. - - `"medium"` + - `code_interpreter: optional object { file_ids }` - - `"high"` + - `file_ids: optional array of string` - - `user_location: optional object { type, city, country, 2 more }` + 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 user's location. + - `file_search: optional object { vector_store_ids }` - - `type: "approximate"` + - `vector_store_ids: optional array of string` - The type of location approximation. Always `approximate`. + 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. - - `"approximate"` +### Example - - `city: optional string` +```http +curl https://api.openai.com/v1/threads/$THREAD_ID \ + -H 'OpenAI-Beta: assistants=v2' \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - Free text input for the city of the user, e.g. `San Francisco`. +#### Response - - `country: optional string` +```json +{ + "id": "id", + "created_at": 0, + "metadata": { + "foo": "string" + }, + "object": "thread", + "tool_resources": { + "code_interpreter": { + "file_ids": [ + "string" + ] + }, + "file_search": { + "vector_store_ids": [ + "string" + ] + } + } +} +``` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. +### Example - - `region: optional string` +```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" +``` - Free text input for the region of the user, e.g. `California`. +#### Response - - `timezone: optional string` +```json +{ + "id": "thread_abc123", + "object": "thread", + "created_at": 1699014083, + "metadata": {}, + "tool_resources": { + "code_interpreter": { + "file_ids": [] + } + } +} +``` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. +## Modify thread - - `ApplyPatch object { type, allowed_callers }` +**post** `/threads/{thread_id}` - Allows the assistant to create, delete, or update files using unified diffs. +Modifies a thread. - - `type: "apply_patch"` +### Path Parameters - The type of the tool. Always `apply_patch`. +- `thread_id: string` - - `"apply_patch"` +### Body Parameters - - `allowed_callers: optional array of "direct" or "programmatic"` +- `metadata: optional Metadata` - The tool invocation context(s). + 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. - - `"direct"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `"programmatic"` +- `tool_resources: optional object { code_interpreter, file_search }` - - `type: "tool_search_output"` + 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. - The type of the item. Always `tool_search_output`. + - `code_interpreter: optional object { file_ids }` - - `"tool_search_output"` + - `file_ids: optional array of string` - - `agent: optional object { agent_name }` + 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 agent that produced this item. + - `file_search: optional object { vector_store_ids }` - - `agent_name: string` + - `vector_store_ids: optional array of string` - The canonical name of the agent that produced this item. + 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. - - `created_by: optional string` +### Returns - The identifier of the actor that created the item. +- `Thread object { id, created_at, metadata, 2 more }` - - `AdditionalTools object { id, role, tools, 2 more }` + Represents a thread that contains [messages](/docs/api-reference/messages). - `id: string` - The unique ID of the additional tools item. + The identifier, which can be referenced in API endpoints. - - `role: "unknown" or "user" or "assistant" or 5 more` + - `created_at: number` - The role that provided the additional tools. + The Unix timestamp (in seconds) for when the thread was created. - - `"unknown"` + - `metadata: Metadata` - - `"user"` + 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. - - `"assistant"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `"system"` + - `object: "thread"` - - `"critic"` + The object type, which is always `thread`. - - `"discriminator"` + - `"thread"` - - `"developer"` + - `tool_resources: object { code_interpreter, file_search }` - - `"tool"` + 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. - - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` + - `code_interpreter: optional object { file_ids }` - The additional tool definitions made available at this item. + - `file_ids: optional array of string` - - `Function object { name, parameters, strict, 5 more }` + 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. - 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: optional object { vector_store_ids }` - - `name: string` + - `vector_store_ids: optional array of string` - The name of the function to call. + 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. - - `parameters: map[unknown]` +### Example - A JSON schema object describing the parameters of the function. +```http +curl https://api.openai.com/v1/threads/$THREAD_ID \ + -H 'Content-Type: application/json' \ + -H 'OpenAI-Beta: assistants=v2' \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{}' +``` - - `strict: boolean` +#### Response - Whether strict parameter validation is enforced for this function tool. +```json +{ + "id": "id", + "created_at": 0, + "metadata": { + "foo": "string" + }, + "object": "thread", + "tool_resources": { + "code_interpreter": { + "file_ids": [ + "string" + ] + }, + "file_search": { + "vector_store_ids": [ + "string" + ] + } + } +} +``` - - `type: "function"` +### Example - The type of the function tool. Always `function`. +```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" \ + -d '{ + "metadata": { + "modified": "true", + "user": "abc123" + } + }' +``` - - `"function"` +#### Response - - `allowed_callers: optional array of "direct" or "programmatic"` +```json +{ + "id": "thread_abc123", + "object": "thread", + "created_at": 1699014083, + "metadata": { + "modified": "true", + "user": "abc123" + }, + "tool_resources": {} +} +``` - The tool invocation context(s). +## Delete thread - - `"direct"` +**delete** `/threads/{thread_id}` - - `"programmatic"` +Delete a thread. - - `defer_loading: optional boolean` +### Path Parameters - Whether this function is deferred and loaded via tool search. +- `thread_id: string` - - `description: optional string` +### Returns - A description of the function. Used by the model to determine whether or not to call the function. +- `ThreadDeleted object { id, deleted, object }` - - `output_schema: optional map[unknown]` + - `id: string` - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `deleted: boolean` - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + - `object: "thread.deleted"` - 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). + - `"thread.deleted"` - - `type: "file_search"` +### Example - The type of the file search tool. Always `file_search`. +```http +curl https://api.openai.com/v1/threads/$THREAD_ID \ + -X DELETE \ + -H 'OpenAI-Beta: assistants=v2' \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - - `"file_search"` +#### Response - - `vector_store_ids: array of string` +```json +{ + "id": "id", + "deleted": true, + "object": "thread.deleted" +} +``` - The IDs of the vector stores to search. +### Example - - `filters: optional object { key, type, value } or object { filters, type }` +```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 +``` - A filter to apply. +#### Response - - `ComparisonFilter object { key, type, value }` +```json +{ + "id": "thread_abc123", + "object": "thread.deleted", + "deleted": true +} +``` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. +## Domain Types - - `key: string` +### Assistant Response Format Option - The key to compare against the value. +- `AssistantResponseFormatOption = "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` - - `type: "eq" or "ne" or "gt" or 5 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`. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + 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). - - `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 JSON mode, which ensures the message the model generates is valid JSON. - - `"eq"` + **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. - - `"ne"` + - `"auto"` - - `"gt"` + `auto` is the default value - - `"gte"` + - `"auto"` - - `"lt"` + - `ResponseFormatText object { type }` - - `"lte"` + Default response format. Used to generate text responses. - - `"in"` + - `type: "text"` - - `"nin"` + The type of response format being defined. Always `text`. - - `value: string or number or boolean or array of string or number` + - `"text"` - The value to compare against the attribute key; supports string, number, or boolean types. + - `ResponseFormatJSONObject object { type }` - - `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. - - `number` + - `type: "json_object"` - - `boolean` + The type of response format being defined. Always `json_object`. - - `array of string or number` + - `"json_object"` - - `string` + - `ResponseFormatJSONSchema object { json_schema, type }` - - `number` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - - `CompoundFilter object { filters, type }` + - `json_schema: object { name, description, schema, strict }` - Combine multiple filters using `and` or `or`. + Structured Outputs configuration options, including a JSON Schema. - - `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 response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - - `ComparisonFilter object { key, type, value }` + - `description: optional string` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `key: string` + - `schema: optional map[unknown]` - The key to compare against the value. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `type: "eq" or "ne" or "gt" or 5 more` + - `strict: optional boolean` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + 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). - - `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: "json_schema"` - - `"eq"` + The type of response format being defined. Always `json_schema`. - - `"ne"` + - `"json_schema"` - - `"gt"` +### Assistant Tool Choice - - `"gte"` +- `AssistantToolChoice object { type, function }` - - `"lt"` + Specifies a tool the model should use. Use to force the model to call a specific tool. - - `"lte"` + - `type: "function" or "code_interpreter" or "file_search"` - - `"in"` + The type of the tool. If type is `function`, the function name must be set - - `"nin"` + - `"function"` - - `value: string or number or boolean or array of string or number` + - `"code_interpreter"` - The value to compare against the attribute key; supports string, number, or boolean types. + - `"file_search"` - - `string` + - `function: optional AssistantToolChoiceFunction` - - `number` + - `name: string` - - `boolean` + The name of the function to call. - - `array of string or number` +### Assistant Tool Choice Function - - `string` +- `AssistantToolChoiceFunction object { name }` - - `number` + - `name: string` - - `unknown` + The name of the function to call. - - `type: "and" or "or"` +### Assistant Tool Choice Option - Type of operation: `and` or `or`. +- `AssistantToolChoiceOption = "none" or "auto" or "required" or AssistantToolChoice` - - `"and"` + 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. - - `"or"` + - `"none" or "auto" or "required"` - - `max_num_results: optional 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. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `"none"` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `"auto"` - Ranking options for search. + - `"required"` - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `AssistantToolChoice object { type, function }` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + Specifies a tool the model should use. Use to force the model to call a specific tool. - - `embedding_weight: number` + - `type: "function" or "code_interpreter" or "file_search"` - The weight of the embedding in the reciprocal ranking fusion. + The type of the tool. If type is `function`, the function name must be set - - `text_weight: number` + - `"function"` - The weight of the text in the reciprocal ranking fusion. + - `"code_interpreter"` - - `ranker: optional "auto" or "default-2024-11-15"` + - `"file_search"` - The ranker to use for the file search. + - `function: optional AssistantToolChoiceFunction` - - `"auto"` + - `name: string` - - `"default-2024-11-15"` + The name of the function to call. - - `score_threshold: optional number` +### Thread - 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 object { id, created_at, metadata, 2 more }` - - `Computer object { type }` + Represents a thread that contains [messages](/docs/api-reference/messages). - 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 identifier, which can be referenced in API endpoints. - The type of the computer tool. Always `computer`. + - `created_at: number` - - `"computer"` + The Unix timestamp (in seconds) for when the thread was created. - - `ComputerUsePreview object { display_height, display_width, environment, type }` + - `metadata: Metadata` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + 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. - - `display_height: number` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The height of the computer display. + - `object: "thread"` - - `display_width: number` + The object type, which is always `thread`. - The width of the computer display. + - `"thread"` - - `environment: "windows" or "mac" or "linux" or 2 more` + - `tool_resources: object { code_interpreter, file_search }` - The type of computer environment to control. + 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. - - `"windows"` + - `code_interpreter: optional object { file_ids }` - - `"mac"` + - `file_ids: optional array of string` - - `"linux"` + 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. - - `"ubuntu"` + - `file_search: optional object { vector_store_ids }` - - `"browser"` + - `vector_store_ids: optional array of string` - - `type: "computer_use_preview"` + 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. - The type of the computer use tool. Always `computer_use_preview`. +### Thread Deleted - - `"computer_use_preview"` +- `ThreadDeleted object { id, deleted, object }` - - `WebSearch object { type, filters, search_context_size, user_location }` + - `id: string` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `deleted: boolean` - - `type: "web_search" or "web_search_2025_08_26"` + - `object: "thread.deleted"` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `"thread.deleted"` - - `"web_search"` +# Runs - - `"web_search_2025_08_26"` +## List runs - - `filters: optional object { allowed_domains }` +**get** `/threads/{thread_id}/runs` - Filters for the search. +Returns a list of runs belonging to a thread. - - `allowed_domains: optional array of string` +### Path Parameters - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. +- `thread_id: string` - Example: `["pubmed.ncbi.nlm.nih.gov"]` +### Query Parameters - - `search_context_size: optional "low" or "medium" or "high"` +- `after: optional string` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + A 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. - - `"low"` +- `before: optional string` - - `"medium"` + 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. - - `"high"` +- `limit: optional number` - - `user_location: optional object { city, country, region, 2 more }` + A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. - The approximate location of the user. +- `order: optional "asc" or "desc"` - - `city: optional string` + Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. - Free text input for the city of the user, e.g. `San Francisco`. + - `"asc"` - - `country: optional string` + - `"desc"` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. +### Returns - - `region: optional string` +- `data: array of Run` - Free text input for the region of the user, e.g. `California`. + - `id: string` - - `timezone: optional string` + The identifier, which can be referenced in API endpoints. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `assistant_id: string` - - `type: optional "approximate"` + The ID of the [assistant](/docs/api-reference/assistants) used for execution of this run. - The type of location approximation. Always `approximate`. + - `cancelled_at: number` - - `"approximate"` + The Unix timestamp (in seconds) for when the run was cancelled. - - `Mcp object { server_label, type, allowed_callers, 9 more }` + - `completed_at: number` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + The Unix timestamp (in seconds) for when the run was completed. - - `server_label: string` + - `created_at: number` - A label for this MCP server, used to identify it in tool calls. + The Unix timestamp (in seconds) for when the run was created. - - `type: "mcp"` + - `expires_at: number` - The type of the MCP tool. Always `mcp`. + The Unix timestamp (in seconds) for when the run will expire. - - `"mcp"` + - `failed_at: number` - - `allowed_callers: optional array of "direct" or "programmatic"` + The Unix timestamp (in seconds) for when the run failed. - The tool invocation context(s). + - `incomplete_details: object { reason }` - - `"direct"` + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - - `"programmatic"` + - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - List of allowed tool names or a filter object. + - `"max_completion_tokens"` - - `McpAllowedTools = array of string` + - `"max_prompt_tokens"` - A string array of allowed tool names + - `instructions: string` - - `McpToolFilter object { read_only, tool_names }` + The instructions that the [assistant](/docs/api-reference/assistants) used for this run. - A filter object to specify which tools are allowed. + - `last_error: object { code, message }` - - `read_only: optional boolean` + The last error associated with this run. Will be `null` if there are no errors. - 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: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` - - `tool_names: optional array of string` + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - List of allowed tool names. + - `"server_error"` - - `authorization: optional string` + - `"rate_limit_exceeded"` - 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. + - `"invalid_prompt"` - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + - `message: 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + A human-readable description of the error. - Currently supported `connector_id` values are: + - `max_completion_tokens: 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 completion tokens specified to have been used over the course of the run. - - `"connector_dropbox"` + - `max_prompt_tokens: number` - - `"connector_gmail"` + The maximum number of prompt tokens specified to have been used over the course of the run. - - `"connector_googlecalendar"` + - `metadata: Metadata` - - `"connector_googledrive"` + 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. - - `"connector_microsoftteams"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `"connector_outlookcalendar"` + - `model: string` - - `"connector_outlookemail"` + The model that the [assistant](/docs/api-reference/assistants) used for this run. - - `"connector_sharepoint"` + - `object: "thread.run"` - - `defer_loading: optional boolean` + The object type, which is always `thread.run`. - Whether this MCP tool is deferred and discovered via tool search. + - `"thread.run"` - - `headers: optional map[string]` + - `parallel_tool_calls: boolean` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + Whether to enable [parallel function calling](/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `require_approval: optional object { always, never } or "always" or "never"` + - `required_action: object { submit_tool_outputs, type }` - Specify which of the MCP server's tools require approval. + Details on the action required to continue the run. Will be `null` if no action is required. - - `McpToolApprovalFilter object { always, never }` + - `submit_tool_outputs: object { tool_calls }` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + Details on the tool outputs needed for this run to continue. - - `always: optional object { read_only, tool_names }` + - `tool_calls: array of RequiredActionFunctionToolCall` - A filter object to specify which tools are allowed. + A list of the relevant tool calls. - - `read_only: optional boolean` + - `id: string` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + The ID of the 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. - - `tool_names: optional array of string` + - `function: object { arguments, name }` - List of allowed tool names. + The function definition. - - `never: optional object { read_only, tool_names }` + - `arguments: string` - A filter object to specify which tools are allowed. + The arguments that the model expects you to pass to the function. - - `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. - - `tool_names: optional array of string` + - `type: "function"` - List of allowed tool names. + The type of tool call the output is required for. For now, this is always `function`. - - `McpToolApprovalSetting = "always" or "never"` + - `"function"` - 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: "submit_tool_outputs"` - - `"always"` + For now, this is always `submit_tool_outputs`. - - `"never"` + - `"submit_tool_outputs"` - - `server_description: optional string` + - `response_format: AssistantResponseFormatOption` - Optional description of the MCP server, used to provide more context. + 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`. - - `server_url: 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 URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `tunnel_id: optional 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 Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. + - `"auto"` - - `CodeInterpreter object { container, type, allowed_callers }` + `auto` is the default value - A tool that runs Python code to help generate a response to a prompt. + - `"auto"` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + - `ResponseFormatText object { type }` - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + Default response format. Used to generate text responses. - - `string` + - `type: "text"` - The container ID. + The type of response format being defined. Always `text`. - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + - `"text"` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `ResponseFormatJSONObject object { type }` - - `type: "auto"` + 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 `auto`. + - `type: "json_object"` - - `"auto"` + The type of response format being defined. Always `json_object`. - - `file_ids: optional array of string` + - `"json_object"` - An optional list of uploaded files to make available to your code. + - `ResponseFormatJSONSchema object { json_schema, type }` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - The memory limit for the code interpreter container. + - `json_schema: object { name, description, schema, strict }` - - `"1g"` + Structured Outputs configuration options, including a JSON Schema. - - `"4g"` + - `name: string` - - `"16g"` + 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. - - `"64g"` + - `description: optional string` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + A description of what the response format is for, used by the model to + determine how to respond in the format. - Network access policy for the container. + - `schema: optional map[unknown]` - - `BetaContainerNetworkPolicyDisabled object { type }` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `strict: optional boolean` - - `type: "code_interpreter"` + 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 code interpreter tool. Always `code_interpreter`. + - `type: "json_schema"` - - `"code_interpreter"` + 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). + - `started_at: number` - - `"direct"` + The Unix timestamp (in seconds) for when the run was started. - - `"programmatic"` + - `status: "queued" or "in_progress" or "requires_action" or 6 more` - - `ProgrammaticToolCalling object { type }` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - - `type: "programmatic_tool_calling"` + - `"queued"` - The type of the tool. Always `programmatic_tool_calling`. + - `"in_progress"` - - `"programmatic_tool_calling"` + - `"requires_action"` - - `ImageGeneration object { type, action, background, 9 more }` + - `"cancelling"` - A tool that generates images using the GPT image models. + - `"cancelled"` - - `type: "image_generation"` + - `"failed"` - The type of the image generation tool. Always `image_generation`. + - `"completed"` - - `"image_generation"` + - `"incomplete"` - - `action: optional "generate" or "edit" or "auto"` + - `"expired"` - Whether to generate a new image or edit an existing image. Default: `auto`. + - `thread_id: string` - - `"generate"` + The ID of the [thread](/docs/api-reference/threads) that was executed on as a part of this run. - - `"edit"` + - `tool_choice: AssistantToolChoiceOption` - - `"auto"` + 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. - - `background: optional "transparent" or "opaque" or "auto"` + - `"none" or "auto" or "required"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + `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. - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + - `"none"` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `"auto"` - - `"transparent"` + - `"required"` - - `"opaque"` + - `AssistantToolChoice object { type, function }` - - `"auto"` + Specifies a tool the model should use. Use to force the model to call a specific tool. - - `input_fidelity: optional "high" or "low"` + - `type: "function" or "code_interpreter" or "file_search"` - 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 tool. If type is `function`, the function name must be set - - `"high"` + - `"function"` - - `"low"` + - `"code_interpreter"` - - `input_image_mask: optional object { file_id, image_url }` + - `"file_search"` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `function: optional AssistantToolChoiceFunction` - - `file_id: optional string` + - `name: string` - File ID for the mask image. + The name of the function to call. - - `image_url: optional string` + - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool` - Base64-encoded mask image. + The list of tools that the [assistant](/docs/api-reference/assistants) used for this run. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `CodeInterpreterTool object { type }` - The image generation model to use. Default: `gpt-image-1`. + - `type: "code_interpreter"` - - `string` + The type of tool being defined: `code_interpreter` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `"code_interpreter"` - The image generation model to use. Default: `gpt-image-1`. + - `FileSearchTool object { type, file_search }` - - `"gpt-image-1"` + - `type: "file_search"` - - `"gpt-image-1-mini"` + The type of tool being defined: `file_search` - - `"gpt-image-2"` + - `"file_search"` - - `"gpt-image-2-2026-04-21"` + - `file_search: optional object { max_num_results, ranking_options }` - - `"gpt-image-1.5"` + Overrides for the file search tool. - - `"chatgpt-image-latest"` + - `max_num_results: optional number` - - `moderation: optional "auto" or "low"` + 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. - Moderation level for the generated image. Default: `auto`. + 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. - - `"auto"` + - `ranking_options: optional object { score_threshold, ranker }` - - `"low"` + 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. - - `output_compression: optional number` + See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - Compression level for the output image. Default: 100. + - `score_threshold: number` - - `output_format: optional "png" or "webp" or "jpeg"` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `ranker: optional "auto" or "default_2024_08_21"` - - `"png"` + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `"webp"` + - `"auto"` - - `"jpeg"` + - `"default_2024_08_21"` - - `partial_images: optional number` + - `FunctionTool object { function, type }` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `function: FunctionDefinition` - - `quality: optional "low" or "medium" or "high" or "auto"` + - `name: string` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - `"low"` + - `description: optional string` - - `"medium"` + A description of what the function does, used by the model to choose when and how to call the function. - - `"high"` + - `parameters: optional FunctionParameters` - - `"auto"` + 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. - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + Omitting `parameters` defines a function with an empty parameter list. - 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`. + - `strict: optional boolean` - - `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). - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `type: "function"` - 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 tool being defined: `function` - - `"1024x1024"` + - `"function"` - - `"1024x1536"` + - `truncation_strategy: object { type, last_messages }` - - `"1536x1024"` + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `"auto"` + - `type: "auto" or "last_messages"` - - `LocalShell object { type }` + 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`. - A tool that allows the model to execute shell commands in a local environment. + - `"auto"` - - `type: "local_shell"` + - `"last_messages"` - The type of the local shell tool. Always `local_shell`. + - `last_messages: optional number` - - `"local_shell"` + The number of most recent messages from the thread when constructing the context for the run. - - `Shell object { type, allowed_callers, environment }` + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - A tool that allows the model to execute shell commands. + 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.). - - `type: "shell"` + - `completion_tokens: number` - The type of the shell tool. Always `shell`. + Number of completion tokens used over the course of the run. - - `"shell"` + - `prompt_tokens: number` - - `allowed_callers: optional array of "direct" or "programmatic"` + Number of prompt tokens used over the course of the run. - The tool invocation context(s). + - `total_tokens: number` - - `"direct"` + Total number of tokens used (prompt + completion). - - `"programmatic"` + - `temperature: optional number` - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + The sampling temperature used for this run. If not set, defaults to 1. - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `top_p: optional number` - - `BetaLocalEnvironment object { type, skills }` + The nucleus sampling value used for this run. If not set, defaults to 1. - - `BetaContainerReference object { container_id, type }` +- `first_id: string` - - `Custom object { name, type, allowed_callers, 3 more }` +- `has_more: boolean` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) +- `last_id: string` - - `name: string` +- `object: string` - The name of the custom tool, used to identify it in tool calls. +### Example - - `type: "custom"` +```http +curl https://api.openai.com/v1/threads/$THREAD_ID/runs \ + -H 'OpenAI-Beta: assistants=v2' \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - The type of the custom tool. Always `custom`. +#### Response - - `"custom"` +```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": [ + { + "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 + } + ], + "first_id": "run_abc123", + "has_more": false, + "last_id": "run_abc456", + "object": "list" +} +``` - - `allowed_callers: optional array of "direct" or "programmatic"` +### Example - The tool invocation context(s). +```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" +``` - - `"direct"` +#### Response - - `"programmatic"` +```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 +} +``` - - `defer_loading: optional boolean` +## Create run - Whether this tool should be deferred and discovered via tool search. +**post** `/threads/{thread_id}/runs` - - `description: optional string` +Create a run. - Optional description of the custom tool, used to provide more context. +### Path Parameters - - `format: optional object { type } or object { definition, syntax, type }` +- `thread_id: string` - The input format for the custom tool. Default is unconstrained text. +### Query Parameters - - `Text object { type }` +- `include: optional array of RunStepInclude` - Unconstrained free-form text. + 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. - - `type: "text"` + See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - Unconstrained text format. Always `text`. + - `"step_details.tool_calls[*].file_search.results[*].content"` - - `"text"` +### Body Parameters - - `Grammar object { definition, syntax, type }` +- `assistant_id: string` - A grammar defined by the user. + The ID of the [assistant](/docs/api-reference/assistants) to use to execute this run. - - `definition: string` +- `additional_instructions: optional string` - The grammar definition. + 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. - - `syntax: "lark" or "regex"` +- `additional_messages: optional array of object { content, role, attachments, metadata }` - The syntax of the grammar definition. One of `lark` or `regex`. + Adds additional messages to the thread before creating the run. - - `"lark"` + - `content: string or array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlockParam` - - `"regex"` + The text contents of the message. - - `type: "grammar"` + - `TextContent = string` - Grammar format. Always `grammar`. + The text contents of the message. - - `"grammar"` + - `ArrayOfContentParts = array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlockParam` - - `Namespace object { description, name, tools, type }` + 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). - Groups function/custom tools under a shared namespace. + - `ImageFileContentBlock object { image_file, type }` - - `description: string` + References an image [File](/docs/api-reference/files) in the content of a message. - A description of the namespace shown to the model. + - `image_file: ImageFile` - - `name: string` + - `file_id: string` - The namespace name used in tool calls (for example, `crm`). + 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. - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + - `detail: optional "auto" or "low" or "high"` - The function/custom tools available inside this namespace. + 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 object { name, type, allowed_callers, 5 more }` + - `"auto"` - - `name: string` + - `"low"` - - `type: "function"` + - `"high"` - - `"function"` + - `type: "image_file"` - - `allowed_callers: optional array of "direct" or "programmatic"` + Always `image_file`. - The tool invocation context(s). + - `"image_file"` - - `"direct"` + - `ImageURLContentBlock object { image_url, type }` - - `"programmatic"` + References an image URL in the content of a message. - - `defer_loading: optional boolean` + - `image_url: ImageURL` - Whether this function should be deferred and discovered via tool search. + - `url: string` - - `description: optional string` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `output_schema: optional map[unknown]` + - `detail: optional "auto" or "low" or "high"` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - - `parameters: optional unknown` + - `"auto"` - - `strict: optional boolean` + - `"low"` - 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. + - `"high"` - - `Custom object { name, type, allowed_callers, 3 more }` + - `type: "image_url"` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The type of the content part. - - `name: string` + - `"image_url"` - The name of the custom tool, used to identify it in tool calls. + - `TextContentBlockParam object { text, type }` - - `type: "custom"` + The text content that is part of a message. - The type of the custom tool. Always `custom`. + - `text: string` - - `"custom"` + Text content to be sent to the model - - `allowed_callers: optional array of "direct" or "programmatic"` + - `type: "text"` - The tool invocation context(s). + Always `text`. - - `"direct"` + - `"text"` - - `"programmatic"` + - `role: "user" or "assistant"` - - `defer_loading: optional boolean` + The role of the entity that is creating the message. Allowed values include: - Whether this tool should be deferred and discovered via tool search. + - `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. - - `description: optional string` + - `"user"` - Optional description of the custom tool, used to provide more context. + - `"assistant"` - - `format: optional object { type } or object { definition, syntax, type }` + - `attachments: optional array of object { file_id, tools }` - The input format for the custom tool. Default is unconstrained text. + A list of files attached to the message, and the tools they should be added to. - - `Text object { type }` + - `file_id: optional string` - Unconstrained free-form text. + The ID of the file to attach to the message. - - `type: "text"` + - `tools: optional array of CodeInterpreterTool or object { type }` - Unconstrained text format. Always `text`. + The tools to add this file to. - - `"text"` + - `CodeInterpreterTool object { type }` - - `Grammar object { definition, syntax, type }` + - `type: "code_interpreter"` - A grammar defined by the user. + The type of tool being defined: `code_interpreter` - - `definition: string` + - `"code_interpreter"` - The grammar definition. + - `FileSearchTool object { type }` - - `syntax: "lark" or "regex"` + - `type: "file_search"` - The syntax of the grammar definition. One of `lark` or `regex`. + The type of tool being defined: `file_search` - - `"lark"` + - `"file_search"` - - `"regex"` + - `metadata: optional Metadata` - - `type: "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. - Grammar format. Always `grammar`. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `"grammar"` +- `instructions: optional string` - - `type: "namespace"` + Overrides the [instructions](/docs/api-reference/assistants/createAssistant) of the assistant. This is useful for modifying the behavior on a per-run basis. - The type of the tool. Always `namespace`. +- `max_completion_tokens: optional number` - - `"namespace"` + 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. - - `ToolSearch object { type, description, execution, parameters }` +- `max_prompt_tokens: optional number` - Hosted or BYOT tool search configuration for deferred tools. + 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. - - `type: "tool_search"` +- `metadata: optional Metadata` - The type of the tool. Always `tool_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. - - `"tool_search"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `description: optional string` +- `model: optional string or "gpt-5" or "gpt-5-mini" or "gpt-5-nano" or 39 more` - Description shown to the model for a client-executed tool search tool. + 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. - - `execution: optional "server" or "client"` + - `string` - Whether tool search is executed by the server or by the client. + - `AssistantSupportedModels = "gpt-5" or "gpt-5-mini" or "gpt-5-nano" or 39 more` - - `"server"` + 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. - - `"client"` + - `"gpt-5"` - - `parameters: optional unknown` + - `"gpt-5-mini"` - Parameter schema for a client-executed tool search tool. + - `"gpt-5-nano"` - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + - `"gpt-5-2025-08-07"` - 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). + - `"gpt-5-mini-2025-08-07"` - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `"gpt-5-nano-2025-08-07"` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `"gpt-4.1"` - - `"web_search_preview"` + - `"gpt-4.1-mini"` - - `"web_search_preview_2025_03_11"` + - `"gpt-4.1-nano"` - - `search_content_types: optional array of "text" or "image"` + - `"gpt-4.1-2025-04-14"` - - `"text"` + - `"gpt-4.1-mini-2025-04-14"` - - `"image"` + - `"gpt-4.1-nano-2025-04-14"` - - `search_context_size: optional "low" or "medium" or "high"` + - `"o3-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. + - `"o3-mini-2025-01-31"` - - `"low"` + - `"o1"` - - `"medium"` + - `"o1-2024-12-17"` - - `"high"` + - `"gpt-4o"` - - `user_location: optional object { type, city, country, 2 more }` + - `"gpt-4o-2024-11-20"` - The user's location. + - `"gpt-4o-2024-08-06"` - - `type: "approximate"` + - `"gpt-4o-2024-05-13"` - The type of location approximation. Always `approximate`. + - `"gpt-4o-mini"` - - `"approximate"` + - `"gpt-4o-mini-2024-07-18"` - - `city: optional string` + - `"gpt-4.5-preview"` - Free text input for the city of the user, e.g. `San Francisco`. + - `"gpt-4.5-preview-2025-02-27"` - - `country: optional string` + - `"gpt-4-turbo"` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `"gpt-4-turbo-2024-04-09"` - - `region: optional string` + - `"gpt-4-0125-preview"` - Free text input for the region of the user, e.g. `California`. + - `"gpt-4-turbo-preview"` - - `timezone: optional string` + - `"gpt-4-1106-preview"` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `"gpt-4-vision-preview"` - - `ApplyPatch object { type, allowed_callers }` + - `"gpt-4"` - Allows the assistant to create, delete, or update files using unified diffs. + - `"gpt-4-0314"` - - `type: "apply_patch"` + - `"gpt-4-0613"` - The type of the tool. Always `apply_patch`. + - `"gpt-4-32k"` - - `"apply_patch"` + - `"gpt-4-32k-0314"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"gpt-4-32k-0613"` - The tool invocation context(s). + - `"gpt-3.5-turbo"` - - `"direct"` + - `"gpt-3.5-turbo-16k"` - - `"programmatic"` + - `"gpt-3.5-turbo-0613"` - - `type: "additional_tools"` + - `"gpt-3.5-turbo-1106"` - The type of the item. Always `additional_tools`. + - `"gpt-3.5-turbo-0125"` - - `"additional_tools"` + - `"gpt-3.5-turbo-16k-0613"` - - `agent: optional object { agent_name }` +- `parallel_tool_calls: optional boolean` - The agent that produced this item. + Whether to enable [parallel function calling](/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `agent_name: string` +- `reasoning_effort: optional ReasoningEffort` - 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. - - `Reasoning object { id, summary, type, 4 more }` + - `"none"` - 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](https://platform.openai.com/docs/guides/conversation-state). + - `"minimal"` - - `id: string` + - `"low"` - The unique identifier of the reasoning content. + - `"medium"` - - `summary: array of object { text, type }` + - `"high"` - Reasoning summary content. + - `"xhigh"` - - `text: string` + - `"max"` - A summary of the reasoning output from the model so far. +- `response_format: optional AssistantResponseFormatOption` - - `type: "summary_text"` + 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 the object. Always `summary_text`. + 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). - - `"summary_text"` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `type: "reasoning"` + **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 object. Always `reasoning`. + - `"auto"` - - `"reasoning"` + `auto` is the default value - - `agent: optional object { agent_name }` + - `"auto"` - The agent that produced this item. + - `ResponseFormatText object { type }` - - `agent_name: string` + Default response format. Used to generate text responses. - The canonical name of the agent that produced this item. + - `type: "text"` - - `content: optional array of object { text, type }` + The type of response format being defined. Always `text`. - Reasoning text content. + - `"text"` - - `text: string` + - `ResponseFormatJSONObject object { type }` - The reasoning text from the model. + 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: "reasoning_text"` + - `type: "json_object"` - The type of the reasoning text. Always `reasoning_text`. + The type of response format being defined. Always `json_object`. - - `"reasoning_text"` + - `"json_object"` - - `encrypted_content: optional string` + - `ResponseFormatJSONSchema object { json_schema, type }` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - - `status: optional "in_progress" or "completed" or "incomplete"` + - `json_schema: object { name, description, schema, strict }` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Structured Outputs configuration options, including a JSON Schema. - - `"in_progress"` + - `name: string` - - `"completed"` + 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. - - `"incomplete"` + - `description: optional string` - - `Program object { id, call_id, code, 3 more }` + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `id: string` + - `schema: optional map[unknown]` - The unique ID of the program item. + 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 stable call ID of the program 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). - - `code: string` + - `type: "json_schema"` - The JavaScript source executed by programmatic tool calling. + The type of response format being defined. Always `json_schema`. - - `fingerprint: string` + - `"json_schema"` - Opaque program replay fingerprint that must be round-tripped. +- `stream: optional boolean` - - `type: "program"` + 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. - The type of the item. Always `program`. +- `temperature: optional number` - - `"program"` + 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. - - `agent: optional object { agent_name }` +- `tool_choice: optional AssistantToolChoiceOption` - The agent that produced this item. + 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. - - `agent_name: string` + - `"none" or "auto" or "required"` - The canonical name of the agent that produced this item. + `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. - - `ProgramOutput object { id, call_id, result, 3 more }` + - `"none"` - - `id: string` + - `"auto"` - The unique ID of the program output item. + - `"required"` - - `call_id: string` + - `AssistantToolChoice object { type, function }` - The call ID of the program item. + Specifies a tool the model should use. Use to force the model to call a specific tool. - - `result: string` + - `type: "function" or "code_interpreter" or "file_search"` - The result produced by the program item. + The type of the tool. If type is `function`, the function name must be set - - `status: "completed" or "incomplete"` + - `"function"` - The terminal status of the program output item. + - `"code_interpreter"` - - `"completed"` + - `"file_search"` - - `"incomplete"` + - `function: optional AssistantToolChoiceFunction` - - `type: "program_output"` + - `name: string` - The type of the item. Always `program_output`. + The name of the function to call. - - `"program_output"` +- `tools: optional array of CodeInterpreterTool or FileSearchTool or FunctionTool` - - `agent: optional object { agent_name }` + Override the tools the assistant can use for this run. This is useful for modifying the behavior on a per-run basis. - The agent that produced this item. + - `CodeInterpreterTool object { type }` - - `agent_name: string` + - `FileSearchTool object { type, file_search }` - The canonical name of the agent that produced this item. + - `type: "file_search"` - - `Compaction object { id, encrypted_content, type, 2 more }` + The type of tool being defined: `file_search` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `"file_search"` - - `id: string` + - `file_search: optional object { max_num_results, ranking_options }` - The unique ID of the compaction item. + Overrides for the file search tool. - - `encrypted_content: string` + - `max_num_results: optional number` - The encrypted content that was produced by compaction. + 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: "compaction"` + 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 the item. Always `compaction`. + - `ranking_options: optional object { score_threshold, ranker }` - - `"compaction"` + 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"` - - `created_by: optional string` + The ranker to use for the file search. If not specified will use the `auto` ranker. - The identifier of the actor that created the item. + - `"auto"` - - `ImageGenerationCall object { id, result, status, 2 more }` + - `"default_2024_08_21"` - An image generation request made by the model. + - `FunctionTool object { function, type }` - - `id: string` + - `function: FunctionDefinition` - The unique ID of the image generation call. + - `name: string` - - `result: 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 generated image encoded in base64. + - `description: optional string` - - `status: "in_progress" or "completed" or "generating" or "failed"` + A description of what the function does, used by the model to choose when and how to call the function. - The status of the image generation call. + - `parameters: optional FunctionParameters` - - `"in_progress"` + 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. - - `"completed"` + Omitting `parameters` defines a function with an empty parameter list. - - `"generating"` + - `strict: optional boolean` - - `"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). - - `type: "image_generation_call"` + - `type: "function"` - The type of the image generation call. Always `image_generation_call`. + The type of tool being defined: `function` - - `"image_generation_call"` + - `"function"` - - `agent: optional object { agent_name }` +- `top_p: optional number` - 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. - - `agent_name: string` + We generally recommend altering this or temperature but not both. - The canonical name of the agent that produced this item. +- `truncation_strategy: optional object { type, last_messages }` - - `CodeInterpreterCall object { id, code, container_id, 4 more }` + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - A tool call to run code. + - `type: "auto" or "last_messages"` - - `id: string` + 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 unique ID of the code interpreter tool call. + - `"auto"` - - `code: string` + - `"last_messages"` - The code to run, or null if not available. + - `last_messages: optional number` - - `container_id: string` + The number of most recent messages from the thread when constructing the context for the run. - The ID of the container used to run the code. +### Returns - - `outputs: array of object { logs, type } or object { type, url }` +- `Run object { id, assistant_id, cancelled_at, 24 more }` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + Represents an execution run on a [thread](/docs/api-reference/threads). - - `Logs object { logs, type }` + - `id: string` - The logs output from the code interpreter. + The identifier, which can be referenced in API endpoints. - - `logs: string` + - `assistant_id: string` - The logs output from the code interpreter. + The ID of the [assistant](/docs/api-reference/assistants) used for execution of this run. - - `type: "logs"` + - `cancelled_at: number` - The type of the output. Always `logs`. + The Unix timestamp (in seconds) for when the run was cancelled. - - `"logs"` + - `completed_at: number` - - `Image object { type, url }` + The Unix timestamp (in seconds) for when the run was completed. - The image output from the code interpreter. + - `created_at: number` - - `type: "image"` + The Unix timestamp (in seconds) for when the run was created. - The type of the output. Always `image`. + - `expires_at: number` - - `"image"` + The Unix timestamp (in seconds) for when the run will expire. - - `url: string` + - `failed_at: number` - The URL of the image output from the code interpreter. + The Unix timestamp (in seconds) for when the run failed. - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + - `incomplete_details: object { reason }` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - - `"in_progress"` + - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` - - `"completed"` + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - - `"incomplete"` + - `"max_completion_tokens"` - - `"interpreting"` + - `"max_prompt_tokens"` - - `"failed"` + - `instructions: string` - - `type: "code_interpreter_call"` + The instructions that the [assistant](/docs/api-reference/assistants) used for this run. - The type of the code interpreter tool call. Always `code_interpreter_call`. + - `last_error: object { code, message }` - - `"code_interpreter_call"` + The last error associated with this run. Will be `null` if there are no errors. - - `agent: optional object { agent_name }` + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` - The agent that produced this item. + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - - `agent_name: string` + - `"server_error"` - The canonical name of the agent that produced this item. + - `"rate_limit_exceeded"` - - `LocalShellCall object { id, action, call_id, 3 more }` + - `"invalid_prompt"` - A tool call to run a command on the local shell. + - `message: string` - - `id: string` + A human-readable description of the error. - The unique ID of the local shell call. + - `max_completion_tokens: number` - - `action: object { command, env, type, 3 more }` + The maximum number of completion tokens specified to have been used over the course of the run. - Execute a shell command on the server. + - `max_prompt_tokens: number` - - `command: array of string` + The maximum number of prompt tokens specified to have been used over the course of the run. - The command to run. + - `metadata: Metadata` - - `env: 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. - Environment variables to set for the command. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `type: "exec"` + - `model: string` - The type of the local shell action. Always `exec`. + The model that the [assistant](/docs/api-reference/assistants) used for this run. - - `"exec"` + - `object: "thread.run"` - - `timeout_ms: optional number` + The object type, which is always `thread.run`. - Optional timeout in milliseconds for the command. + - `"thread.run"` - - `user: optional string` + - `parallel_tool_calls: boolean` - Optional user to run the command as. + Whether to enable [parallel function calling](/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `working_directory: optional string` + - `required_action: object { submit_tool_outputs, type }` - Optional working directory to run the command in. + Details on the action required to continue the run. Will be `null` if no action is required. - - `call_id: string` + - `submit_tool_outputs: object { tool_calls }` - The unique ID of the local shell tool call generated by the model. + Details on the tool outputs needed for this run to continue. - - `status: "in_progress" or "completed" or "incomplete"` + - `tool_calls: array of RequiredActionFunctionToolCall` - The status of the local shell call. + A list of the relevant tool calls. - - `"in_progress"` + - `id: string` - - `"completed"` + 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. - - `"incomplete"` + - `function: object { arguments, name }` - - `type: "local_shell_call"` + The function definition. - The type of the local shell call. Always `local_shell_call`. + - `arguments: string` - - `"local_shell_call"` + The arguments that the model expects you to pass to the function. - - `agent: optional object { agent_name }` + - `name: string` - The agent that produced this item. + The name of the function. - - `agent_name: string` + - `type: "function"` - The canonical name of the agent that produced this item. + The type of tool call the output is required for. For now, this is always `function`. - - `LocalShellCallOutput object { id, output, type, 2 more }` + - `"function"` - The output of a local shell tool call. + - `type: "submit_tool_outputs"` - - `id: string` + For now, this is always `submit_tool_outputs`. - The unique ID of the local shell tool call generated by the model. + - `"submit_tool_outputs"` - - `output: string` + - `response_format: AssistantResponseFormatOption` - A JSON string of the output of the local shell tool call. + 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`. - - `type: "local_shell_call_output"` + 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 type of the local shell tool call output. Always `local_shell_call_output`. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `"local_shell_call_output"` + **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: optional object { agent_name }` + - `"auto"` - The agent that produced this item. + `auto` is the default value - - `agent_name: string` + - `"auto"` - The canonical name of the agent that produced this item. + - `ResponseFormatText 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`. + - `type: "text"` - - `"in_progress"` + The type of response format being defined. Always `text`. - - `"completed"` + - `"text"` - - `"incomplete"` + - `ResponseFormatJSONObject object { type }` - - `ShellCall object { id, action, call_id, 6 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. - A tool call that executes one or more shell commands in a managed environment. + - `type: "json_object"` - - `id: string` + The type of response format being defined. Always `json_object`. - The unique ID of the shell tool call. Populated when this item is returned via API. + - `"json_object"` - - `action: object { commands, max_output_length, timeout_ms }` + - `ResponseFormatJSONSchema object { json_schema, type }` - The shell commands and limits that describe how to run the tool call. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - - `commands: array of string` + - `json_schema: object { name, description, schema, strict }` - - `max_output_length: number` + Structured Outputs configuration options, including a JSON Schema. - Optional maximum number of characters to return from each command. + - `name: string` - - `timeout_ms: 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. - Optional timeout in milliseconds for the commands. + - `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 shell tool call generated by the model. + - `schema: optional map[unknown]` - - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - Represents the use of a local environment to perform shell actions. + - `strict: optional boolean` - - `BetaResponseLocalEnvironment object { type }` + 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). - Represents the use of a local environment to perform shell actions. + - `type: "json_schema"` - - `type: "local"` + The type of response format being defined. Always `json_schema`. - The environment type. Always `local`. + - `"json_schema"` - - `"local"` + - `started_at: number` - - `BetaResponseContainerReference object { container_id, type }` + The Unix timestamp (in seconds) for when the run was started. - Represents a container created with /v1/containers. + - `status: "queued" or "in_progress" or "requires_action" or 6 more` - - `container_id: string` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - - `type: "container_reference"` + - `"queued"` - The environment type. Always `container_reference`. + - `"in_progress"` - - `"container_reference"` + - `"requires_action"` - - `status: "in_progress" or "completed" or "incomplete"` + - `"cancelling"` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `"cancelled"` - - `"in_progress"` + - `"failed"` - `"completed"` - `"incomplete"` - - `type: "shell_call"` + - `"expired"` - The type of the item. Always `shell_call`. + - `thread_id: string` - - `"shell_call"` + The ID of the [thread](/docs/api-reference/threads) that was executed on as a part of this run. - - `agent: optional object { agent_name }` + - `tool_choice: AssistantToolChoiceOption` - The agent that produced this item. + 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. - - `agent_name: string` + - `"none" or "auto" or "required"` - The canonical name of the agent that produced this item. + `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. - - `caller: optional object { type } or object { caller_id, type }` + - `"none"` - The execution context that produced this tool call. + - `"auto"` - - `Direct object { type }` + - `"required"` - - `type: "direct"` + - `AssistantToolChoice object { type, function }` - - `"direct"` + Specifies a tool the model should use. Use to force the model to call a specific tool. - - `Program object { caller_id, type }` + - `type: "function" or "code_interpreter" or "file_search"` - - `caller_id: string` + The type of the tool. If type is `function`, the function name must be set - The call ID of the program item that produced this tool call. + - `"function"` - - `type: "program"` + - `"code_interpreter"` - - `"program"` + - `"file_search"` - - `created_by: optional string` + - `function: optional AssistantToolChoiceFunction` - The ID of the entity that created this tool call. + - `name: string` - - `ShellCallOutput object { id, call_id, max_output_length, 6 more }` + The name of the function to call. - The output of a shell tool call that was emitted. + - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool` - - `id: string` + The list of tools that the [assistant](/docs/api-reference/assistants) used for this run. - The unique ID of the shell call output. Populated when this item is returned via API. + - `CodeInterpreterTool object { type }` - - `call_id: string` + - `type: "code_interpreter"` - The unique ID of the shell tool call generated by the model. + The type of tool being defined: `code_interpreter` - - `max_output_length: number` + - `"code_interpreter"` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `FileSearchTool object { type, file_search }` - - `output: array of object { outcome, stderr, stdout, created_by }` + - `type: "file_search"` - An array of shell call output contents + The type of tool being defined: `file_search` - - `outcome: object { type } or object { exit_code, type }` + - `"file_search"` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + - `file_search: optional object { max_num_results, ranking_options }` - - `Timeout object { type }` + Overrides for the file search tool. - Indicates that the shell call exceeded its configured time limit. + - `max_num_results: optional number` - - `type: "timeout"` + 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 outcome type. Always `timeout`. + 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. - - `"timeout"` + - `ranking_options: optional object { score_threshold, ranker }` - - `Exit object { exit_code, 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. - Indicates that the shell commands finished and returned an exit code. + See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `exit_code: number` + - `score_threshold: number` - Exit code from the shell process. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `type: "exit"` + - `ranker: optional "auto" or "default_2024_08_21"` - The outcome type. Always `exit`. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `"exit"` + - `"auto"` - - `stderr: string` + - `"default_2024_08_21"` - The standard error output that was captured. + - `FunctionTool object { function, type }` - - `stdout: string` + - `function: FunctionDefinition` - The standard output that was captured. + - `name: string` - - `created_by: 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 identifier of the actor that created the item. + - `description: optional string` - - `status: "in_progress" or "completed" or "incomplete"` + A description of what the function does, used by the model to choose when and how to call the function. - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + - `parameters: optional FunctionParameters` - - `"in_progress"` + 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. - - `"completed"` + Omitting `parameters` defines a function with an empty parameter list. - - `"incomplete"` + - `strict: optional boolean` - - `type: "shell_call_output"` + 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 type of the shell call output. Always `shell_call_output`. + - `type: "function"` - - `"shell_call_output"` + The type of tool being defined: `function` - - `agent: optional object { agent_name }` + - `"function"` - The agent that produced this item. + - `truncation_strategy: object { type, last_messages }` - - `agent_name: 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 canonical name of the agent that produced this item. + - `type: "auto" or "last_messages"` - - `caller: optional object { type } or object { caller_id, type }` + 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 execution context that produced this tool call. + - `"auto"` - - `Direct object { type }` + - `"last_messages"` - - `type: "direct"` + - `last_messages: optional number` - - `"direct"` + The number of most recent messages from the thread when constructing the context for the run. - - `Program object { caller_id, type }` + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - - `caller_id: 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 call ID of the program item that produced this tool call. + - `completion_tokens: number` - - `type: "program"` + Number of completion tokens used over the course of the run. - - `"program"` + - `prompt_tokens: number` - - `created_by: optional string` + Number of prompt tokens used over the course of the run. - The identifier of the actor that created the item. + - `total_tokens: number` - - `ApplyPatchCall object { id, call_id, operation, 5 more }` + Total number of tokens used (prompt + completion). - A tool call that applies file diffs by creating, deleting, or updating files. + - `temperature: optional number` - - `id: string` + The sampling temperature used for this run. If not set, defaults to 1. - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `top_p: optional number` - - `call_id: string` + The nucleus sampling value used for this run. If not set, defaults to 1. - The unique ID of the apply patch tool call generated by the model. +### Example - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` +```http +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" \ + -d '{ + "assistant_id": "assistant_id", + "temperature": 1, + "top_p": 1 + }' +``` - One of the create_file, delete_file, or update_file operations applied via apply_patch. +#### Response - - `CreateFile object { diff, path, type }` +```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 +} +``` - Instruction describing how to create a file via the apply_patch tool. +### Example - - `diff: string` +```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" + }' +``` - Diff to apply. +#### Response - - `path: string` +```json +{ + "id": "run_abc123", + "object": "thread.run", + "created_at": 1699063290, + "assistant_id": "asst_abc123", + "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": [ + { + "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 +} +``` - Path of the file to create. +### Streaming - - `type: "create_file"` +```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 + }' +``` - Create a new file with the provided diff. +#### Response - - `"create_file"` +```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}} - - `DeleteFile object { path, type }` +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}} - Instruction describing how to delete a file via the apply_patch tool. +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}} - - `path: string` +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} - Path of the file to delete. +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} - - `type: "delete_file"` +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":{}} - Delete the specified file. +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":{}} - - `"delete_file"` +event: thread.message.delta +data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"Hello","annotations":[]}}]}} - - `UpdateFile object { diff, path, type }` +... - Instruction describing how to update a file via the apply_patch tool. +event: thread.message.delta +data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" today"}}]}} - - `diff: string` +event: thread.message.delta +data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"?"}}]}} - Diff to apply. +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":{}} - - `path: string` +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}} - Path of the file to update. +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}} - - `type: "update_file"` +event: done +data: [DONE] +``` - Update an existing file with the provided diff. +### Streaming with Functions - - `"update_file"` +```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 + }' +``` - - `status: "in_progress" or "completed"` +#### Response - The status of the apply patch tool call. One of `in_progress` or `completed`. +```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}} - - `"in_progress"` +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}} - - `"completed"` +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: "apply_patch_call"` +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} - The type of the item. Always `apply_patch_call`. +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} - - `"apply_patch_call"` +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":{}} - - `agent: optional object { agent_name }` +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":{}} - The agent that produced this item. +event: thread.message.delta +data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"Hello","annotations":[]}}]}} - - `agent_name: string` +... - The canonical name of the agent that produced this item. +event: thread.message.delta +data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" today"}}]}} - - `caller: optional object { type } or object { caller_id, type }` +event: thread.message.delta +data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"?"}}]}} - The execution context that produced this tool call. +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":{}} - - `Direct object { type }` +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}} - - `type: "direct"` +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}} - - `"direct"` +event: done +data: [DONE] +``` - - `Program object { caller_id, type }` +## Retrieve run - - `caller_id: string` +**get** `/threads/{thread_id}/runs/{run_id}` - The call ID of the program item that produced this tool call. +Retrieves a run. - - `type: "program"` +### Path Parameters - - `"program"` +- `thread_id: string` - - `created_by: optional string` +- `run_id: string` - The ID of the entity that created this tool call. +### Returns - - `ApplyPatchCallOutput object { id, call_id, status, 5 more }` +- `Run object { id, assistant_id, cancelled_at, 24 more }` - The output emitted by an apply patch tool call. + Represents an execution run on a [thread](/docs/api-reference/threads). - `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 identifier, which can be referenced in API endpoints. - The status of the apply patch tool call output. One of `completed` or `failed`. + - `assistant_id: string` - - `"completed"` + The ID of the [assistant](/docs/api-reference/assistants) used for execution of this run. - - `"failed"` + - `cancelled_at: number` - - `type: "apply_patch_call_output"` + The Unix timestamp (in seconds) for when the run was cancelled. - The type of the item. Always `apply_patch_call_output`. + - `completed_at: number` - - `"apply_patch_call_output"` + The Unix timestamp (in seconds) for when the run was completed. - - `agent: optional object { agent_name }` + - `created_at: number` - The agent that produced this item. + The Unix timestamp (in seconds) for when the run was created. - - `agent_name: string` + - `expires_at: number` - The canonical name of the agent that produced this item. + The Unix timestamp (in seconds) for when the run will expire. - - `caller: optional object { type } or object { caller_id, type }` + - `failed_at: number` - The execution context that produced this tool call. + The Unix timestamp (in seconds) for when the run failed. - - `Direct object { type }` + - `incomplete_details: object { reason }` - - `type: "direct"` + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - - `"direct"` + - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` - - `Program object { caller_id, type }` + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - - `caller_id: string` + - `"max_completion_tokens"` - The call ID of the program item that produced this tool call. + - `"max_prompt_tokens"` - - `type: "program"` + - `instructions: string` - - `"program"` + The instructions that the [assistant](/docs/api-reference/assistants) used for this run. - - `created_by: optional string` + - `last_error: object { code, message }` - The ID of the entity that created this tool call output. + The last error associated with this run. Will be `null` if there are no errors. - - `output: optional string` + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` - Optional textual output returned by the apply patch tool. + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - - `McpListTools object { id, server_label, tools, 3 more }` + - `"server_error"` - A list of tools available on an MCP server. + - `"rate_limit_exceeded"` - - `id: string` + - `"invalid_prompt"` - The unique ID of the list. + - `message: string` - - `server_label: string` + A human-readable description of the error. - The label of the MCP server. + - `max_completion_tokens: number` - - `tools: array of object { input_schema, name, annotations, description }` + The maximum number of completion tokens specified to have been used over the course of the run. - The tools available on the server. + - `max_prompt_tokens: number` - - `input_schema: unknown` + The maximum number of prompt tokens specified to have been used over the course of the run. - The JSON schema describing the tool's input. + - `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 tool. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `annotations: optional unknown` + - `model: string` - Additional annotations about the tool. + The model that the [assistant](/docs/api-reference/assistants) used for this run. - - `description: optional string` + - `object: "thread.run"` - The description of the tool. + The object type, which is always `thread.run`. - - `type: "mcp_list_tools"` + - `"thread.run"` - The type of the item. Always `mcp_list_tools`. + - `parallel_tool_calls: boolean` - - `"mcp_list_tools"` + Whether to enable [parallel function calling](/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `agent: optional object { agent_name }` + - `required_action: object { submit_tool_outputs, type }` - The agent that produced this item. + Details on the action required to continue the run. Will be `null` if no action is required. - - `agent_name: string` + - `submit_tool_outputs: object { tool_calls }` - The canonical name of the agent that produced this item. + Details on the tool outputs needed for this run to continue. - - `error: optional string` + - `tool_calls: array of RequiredActionFunctionToolCall` - Error message if the server could not list tools. + A list of the relevant tool calls. - - `McpApprovalRequest object { id, arguments, name, 3 more }` + - `id: string` - A request for human approval of a tool invocation. + 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. - - `id: string` + - `function: object { arguments, name }` - The unique ID of the approval request. + The function definition. - `arguments: string` - A JSON string of arguments for the tool. + The arguments that the model expects you to pass to the function. - `name: string` - The name of the tool to run. + The name of the function. - - `server_label: string` + - `type: "function"` - The label of the MCP server making the request. + The type of tool call the output is required for. For now, this is always `function`. - - `type: "mcp_approval_request"` + - `"function"` - The type of the item. Always `mcp_approval_request`. + - `type: "submit_tool_outputs"` - - `"mcp_approval_request"` + For now, this is always `submit_tool_outputs`. - - `agent: optional object { agent_name }` + - `"submit_tool_outputs"` - The agent that produced this item. + - `response_format: AssistantResponseFormatOption` - - `agent_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 canonical name of the agent that produced this item. + 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). - - `McpApprovalResponse object { id, approval_request_id, approve, 3 more }` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - A response to an MCP approval request. + **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. - - `id: string` + - `"auto"` - The unique ID of the approval response + `auto` is the default value - - `approval_request_id: string` + - `"auto"` - The ID of the approval request being answered. + - `ResponseFormatText object { type }` - - `approve: boolean` + Default response format. Used to generate text responses. - Whether the request was approved. + - `type: "text"` - - `type: "mcp_approval_response"` + The type of response format being defined. Always `text`. - The type of the item. Always `mcp_approval_response`. + - `"text"` - - `"mcp_approval_response"` + - `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"` - - `reason: optional string` + - `ResponseFormatJSONSchema object { json_schema, type }` - Optional reason for the decision. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - - `McpCall object { id, arguments, name, 7 more }` + - `json_schema: object { name, description, schema, strict }` - An invocation of a tool on an MCP server. + Structured Outputs configuration options, including a JSON Schema. - - `id: string` + - `name: string` - The unique ID of the tool call. + 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. - - `arguments: string` + - `description: optional string` - A JSON string of the arguments passed to the tool. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `name: string` + - `schema: optional map[unknown]` - The name of the tool that was run. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `server_label: string` + - `strict: optional boolean` - The label of the MCP server running the tool. + 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: "mcp_call"` + - `type: "json_schema"` - The type of the item. Always `mcp_call`. + The type of response format being defined. Always `json_schema`. - - `"mcp_call"` + - `"json_schema"` - - `agent: optional object { agent_name }` + - `started_at: number` - The agent that produced this item. + The Unix timestamp (in seconds) for when the run was started. - - `agent_name: string` + - `status: "queued" or "in_progress" or "requires_action" or 6 more` - The canonical name of the agent that produced this item. + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - - `approval_request_id: optional string` + - `"queued"` - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + - `"in_progress"` - - `error: optional string` + - `"requires_action"` - The error from the tool call, if any. + - `"cancelling"` - - `output: optional string` + - `"cancelled"` - The output from the tool call. + - `"failed"` - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `"completed"` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `"incomplete"` - - `"in_progress"` + - `"expired"` - - `"completed"` + - `thread_id: string` - - `"incomplete"` + The ID of the [thread](/docs/api-reference/threads) that was executed on as a part of this run. - - `"calling"` + - `tool_choice: AssistantToolChoiceOption` - - `"failed"` + 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. - - `CustomToolCall object { id, call_id, input, 7 more }` + - `"none" or "auto" or "required"` - - `id: string` + `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 unique ID of the custom tool call item. + - `"none"` - - `call_id: string` + - `"auto"` - An identifier used to map this custom tool call to a tool call output. + - `"required"` - - `input: string` + - `AssistantToolChoice object { type, function }` - The input for the custom tool call generated by the model. + Specifies a tool the model should use. Use to force the model to call a specific tool. - - `name: string` + - `type: "function" or "code_interpreter" or "file_search"` - The name of the custom tool being called. + The type of the tool. If type is `function`, the function name must be set - - `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. + - `"code_interpreter"` - - `"in_progress"` + - `"file_search"` - - `"completed"` + - `function: optional AssistantToolChoiceFunction` - - `"incomplete"` + - `name: string` - - `type: "custom_tool_call"` + The name of the function to call. - The type of the custom tool call. Always `custom_tool_call`. + - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool` - - `"custom_tool_call"` + The list of tools that the [assistant](/docs/api-reference/assistants) used for this run. - - `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"` - - `caller: optional object { type } or object { caller_id, type }` + - `FileSearchTool object { type, file_search }` - The execution context that produced this tool call. + - `type: "file_search"` - - `Direct object { type }` + The type of tool being defined: `file_search` - - `type: "direct"` + - `"file_search"` - - `"direct"` + - `file_search: optional object { max_num_results, ranking_options }` - - `Program object { caller_id, type }` + Overrides for the file search tool. - - `caller_id: string` + - `max_num_results: optional number` - The call ID of the program item that produced this tool call. + 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: "program"` + 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. - - `"program"` + - `ranking_options: optional object { score_threshold, ranker }` - - `created_by: optional 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 identifier of the actor that created the item. + See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `namespace: optional string` + - `score_threshold: number` - The namespace of the custom tool being called. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `CustomToolCallOutput object { id, call_id, output, 5 more }` + - `ranker: optional "auto" or "default_2024_08_21"` - - `id: string` + The ranker to use for the file search. If not specified will use the `auto` ranker. - The unique ID of the custom tool call output item. + - `"auto"` - - `call_id: string` + - `"default_2024_08_21"` - The call ID, used to map this custom tool call output to a custom tool call. + - `FunctionTool object { function, type }` - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `function: FunctionDefinition` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `name: string` - - `StringOutput = string` + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - A string of the output of the custom tool call. + - `description: optional string` - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + A description of what the function does, used by the model to choose when and how to call the function. - Text, image, or file output of the custom tool call. + - `parameters: optional FunctionParameters` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + 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 text input to the model. + Omitting `parameters` defines a function with an empty parameter list. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `strict: optional boolean` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + 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). - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `type: "function"` - A file input to the model. + The type of tool being defined: `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. + - `truncation_strategy: object { type, last_messages }` - - `"in_progress"` + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `"completed"` + - `type: "auto" or "last_messages"` - - `"incomplete"` + 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: "custom_tool_call_output"` + - `"auto"` - The type of the custom tool call output. Always `custom_tool_call_output`. + - `"last_messages"` - - `"custom_tool_call_output"` + - `last_messages: optional number` - - `agent: optional object { agent_name }` + The number of most recent messages from the thread when constructing the context for the run. - The agent that produced this item. + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - - `agent_name: 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 canonical name of the agent that produced this item. + - `completion_tokens: number` - - `caller: optional object { type } or object { caller_id, type }` + Number of completion tokens used over the course of the run. - The execution context that produced this tool call. + - `prompt_tokens: number` - - `Direct object { type }` + Number of prompt tokens used over the course of the run. - - `type: "direct"` + - `total_tokens: number` - The caller type. Always `direct`. + Total number of tokens used (prompt + completion). + + - `temperature: optional number` - - `"direct"` + The sampling temperature used for this run. If not set, defaults to 1. - - `Program object { caller_id, type }` + - `top_p: optional number` - - `caller_id: string` + The nucleus sampling value used for this run. If not set, defaults to 1. - The call ID of the program item that produced this tool call. +### Example - - `type: "program"` +```http +curl https://api.openai.com/v1/threads/$THREAD_ID/runs/$RUN_ID \ + -H 'OpenAI-Beta: assistants=v2' \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - The caller type. Always `program`. +#### Response - - `"program"` +```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 +} +``` - - `created_by: optional string` +### Example - The identifier of the actor that created the item. +```http +curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123 \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "OpenAI-Beta: assistants=v2" +``` - - `first_id: string` +#### Response - The ID of the first item in the list. +```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 +} +``` - - `has_more: boolean` +## Modify run - Whether there are more items available. +**post** `/threads/{thread_id}/runs/{run_id}` - - `last_id: string` +Modifies a run. - The ID of the last item in the list. +### Path Parameters - - `object: "list"` +- `thread_id: string` - The type of object returned, must be `list`. +- `run_id: string` - - `"list"` +### Body Parameters -# Input Tokens +- `metadata: optional Metadata` -## Get input token counts + 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. -**post** `/responses/input_tokens?beta=true` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. -Get input token counts +### Returns -### Header Parameters +- `Run object { id, assistant_id, cancelled_at, 24 more }` -- `"openai-beta": optional array of "responses_multi_agent=v1"` + Represents an execution run on a [thread](/docs/api-reference/threads). - - `"responses_multi_agent=v1"` + - `id: string` -### Body Parameters + The identifier, which can be referenced in API endpoints. -- `conversation: optional string or BetaResponseConversationParam` + - `assistant_id: string` - 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. + The ID of the [assistant](/docs/api-reference/assistants) used for execution of this run. - - `ConversationID = string` + - `cancelled_at: number` - The unique ID of the conversation. + The Unix timestamp (in seconds) for when the run was cancelled. - - `BetaResponseConversationParam object { id }` + - `completed_at: number` - The conversation that this response belongs to. + The Unix timestamp (in seconds) for when the run was completed. - - `id: string` + - `created_at: number` - The unique ID of the conversation. + The Unix timestamp (in seconds) for when the run was created. -- `input: optional string or array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + - `expires_at: number` - Text, image, or file inputs to the model, used to generate a response + The Unix timestamp (in seconds) for when the run will expire. - - `string` + - `failed_at: number` - A text input to the model, equivalent to a text input with the `user` role. + The Unix timestamp (in seconds) for when the run failed. - - `array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + - `incomplete_details: object { reason }` - A list of one or many input items to the model, containing different content types. + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - - `BetaEasyInputMessage object { content, role, phase, type }` + - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` - 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 reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - - `content: string or BetaResponseInputMessageContentList` + - `"max_completion_tokens"` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + - `"max_prompt_tokens"` - - `TextInput = string` + - `instructions: string` - A text input to the model. + The instructions that the [assistant](/docs/api-reference/assistants) used for this run. - - `BetaResponseInputMessageContentList = array of BetaResponseInputContent` + - `last_error: object { code, message }` - A list of one or many input items to the model, containing different content - types. + The last error associated with this run. Will be `null` if there are no errors. - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` - A text input to the model. + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - - `text: string` + - `"server_error"` - The text input to the model. + - `"rate_limit_exceeded"` - - `type: "input_text"` + - `"invalid_prompt"` - The type of the input item. Always `input_text`. + - `message: string` - - `"input_text"` + A human-readable description of the error. - - `prompt_cache_breakpoint: optional object { mode }` + - `max_completion_tokens: 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 number of completion tokens specified to have been used over the course of the run. - - `mode: "explicit"` + - `max_prompt_tokens: number` - The breakpoint mode. Always `explicit`. + The maximum number of prompt tokens specified to have been used over the course of the run. - - `"explicit"` + - `metadata: Metadata` - - `BetaResponseInputImage object { detail, type, file_id, 2 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. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `detail: "low" or "high" or "auto" or "original"` + - `model: string` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The model that the [assistant](/docs/api-reference/assistants) used for this run. - - `"low"` + - `object: "thread.run"` - - `"high"` + The object type, which is always `thread.run`. - - `"auto"` + - `"thread.run"` - - `"original"` + - `parallel_tool_calls: boolean` - - `type: "input_image"` + Whether to enable [parallel function calling](/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - The type of the input item. Always `input_image`. + - `required_action: object { submit_tool_outputs, type }` - - `"input_image"` + 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 ID of the file to be sent to the model. + Details on the tool outputs needed for this run to continue. - - `image_url: optional string` + - `tool_calls: array of RequiredActionFunctionToolCall` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + A list of the relevant tool calls. - - `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 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. - - `mode: "explicit"` + - `function: object { arguments, name }` - The breakpoint mode. Always `explicit`. + The function definition. - - `"explicit"` + - `arguments: string` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + The arguments that the model expects you to pass to the function. - A file input to the model. + - `name: string` - - `type: "input_file"` + The name of the function. - The type of the input item. Always `input_file`. + - `type: "function"` - - `"input_file"` + The type of tool call the output is required for. For now, this is always `function`. - - `detail: optional "auto" or "low" or "high"` + - `"function"` - 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: "submit_tool_outputs"` - - `"auto"` + For now, this is always `submit_tool_outputs`. - - `"low"` + - `"submit_tool_outputs"` - - `"high"` + - `response_format: AssistantResponseFormatOption` - - `file_data: 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 content of the file to be sent to the model. + 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. - - `file_url: optional string` + - `"auto"` - The URL of the file to be sent to the model. + `auto` is the default value - - `filename: optional string` + - `"auto"` - The name of the file to be sent to the model. + - `ResponseFormatText object { type }` - - `prompt_cache_breakpoint: optional object { mode }` + Default response format. Used to generate text responses. - Marks the exact end of a reusable 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: "text"` - - `mode: "explicit"` + The type of response format being defined. Always `text`. - The breakpoint mode. Always `explicit`. + - `"text"` - - `"explicit"` + - `ResponseFormatJSONObject object { type }` - - `role: "user" or "assistant" or "system" or "developer"` + 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 role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + - `type: "json_object"` - - `"user"` + The type of response format being defined. Always `json_object`. - - `"assistant"` + - `"json_object"` - - `"system"` + - `ResponseFormatJSONSchema object { json_schema, type }` - - `"developer"` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - - `phase: optional "commentary" or "final_answer"` + - `json_schema: object { name, description, schema, strict }` - 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. + Structured Outputs configuration options, including a JSON Schema. - - `"commentary"` + - `name: string` - - `"final_answer"` + 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: optional "message"` + - `description: optional string` - The type of the message input. Always `message`. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `"message"` + - `schema: optional map[unknown]` - - `Message object { content, role, agent, 2 more }` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - 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. + - `strict: optional boolean` - - `content: BetaResponseInputMessageContentList` + 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 list of one or many input items to the model, containing different content - types. + - `type: "json_schema"` - - `role: "user" or "system" or "developer"` + The type of response format being defined. Always `json_schema`. - The role of the message input. One of `user`, `system`, or `developer`. + - `"json_schema"` - - `"user"` + - `started_at: number` - - `"system"` + The Unix timestamp (in seconds) for when the run was started. - - `"developer"` + - `status: "queued" or "in_progress" or "requires_action" or 6 more` - - `agent: optional object { agent_name }` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - The agent that produced this item. + - `"queued"` - - `agent_name: string` + - `"in_progress"` - The canonical name of the agent that produced this item. + - `"requires_action"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"cancelling"` - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"cancelled"` - - `"in_progress"` + - `"failed"` - `"completed"` - `"incomplete"` - - `type: optional "message"` + - `"expired"` - The type of the message input. Always set to `message`. + - `thread_id: string` - - `"message"` + The ID of the [thread](/docs/api-reference/threads) that was executed on as a part of this run. - - `BetaResponseOutputMessage object { id, content, role, 4 more }` + - `tool_choice: AssistantToolChoiceOption` - An output message from the model. + 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. - - `id: string` + - `"none" or "auto" or "required"` - The unique ID of the output 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. - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + - `"none"` - The content of the output message. + - `"auto"` - - `BetaResponseOutputText object { annotations, text, type, logprobs }` + - `"required"` - A text output from the model. + - `AssistantToolChoice object { type, function }` - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + Specifies a tool the model should use. Use to force the model to call a specific tool. - The annotations of the text output. + - `type: "function" or "code_interpreter" or "file_search"` - - `FileCitation object { file_id, filename, index, type }` + The type of the tool. If type is `function`, the function name must be set - A citation to a file. + - `"function"` - - `file_id: string` + - `"code_interpreter"` - The ID of the file. + - `"file_search"` - - `filename: string` + - `function: optional AssistantToolChoiceFunction` - The filename of the file cited. + - `name: string` - - `index: number` + The name of the function to call. - The index of the file in the list of files. + - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool` - - `type: "file_citation"` + The list of tools that the [assistant](/docs/api-reference/assistants) used for this run. - The type of the file citation. Always `file_citation`. + - `CodeInterpreterTool object { type }` - - `"file_citation"` + - `type: "code_interpreter"` - - `URLCitation object { end_index, start_index, title, 2 more }` + The type of tool being defined: `code_interpreter` - A citation for a web resource used to generate a model response. + - `"code_interpreter"` - - `end_index: number` + - `FileSearchTool object { type, file_search }` - The index of the last character of the URL citation in the message. + - `type: "file_search"` - - `start_index: number` + The type of tool being defined: `file_search` - The index of the first character of the URL citation in the message. + - `"file_search"` - - `title: string` + - `file_search: optional object { max_num_results, ranking_options }` - The title of the web resource. + Overrides for the file search tool. - - `type: "url_citation"` + - `max_num_results: optional number` - The type of the URL citation. Always `url_citation`. + 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. - - `"url_citation"` + 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. - - `url: string` + - `ranking_options: optional object { score_threshold, ranker }` - The URL of the web resource. + 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. - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - A citation for a container file used to generate a model response. + - `score_threshold: number` - - `container_id: string` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - The ID of the container file. + - `ranker: optional "auto" or "default_2024_08_21"` - - `end_index: number` + The ranker to use for the file search. If not specified will use the `auto` ranker. - The index of the last character of the container file citation in the message. + - `"auto"` - - `file_id: string` + - `"default_2024_08_21"` - The ID of the file. + - `FunctionTool object { function, type }` - - `filename: string` + - `function: FunctionDefinition` - The filename of the container file cited. + - `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 container file citation in the message. + - `description: optional string` - - `type: "container_file_citation"` + A description of what the function does, used by the model to choose when and how to call the function. - The type of the container file citation. Always `container_file_citation`. + - `parameters: optional FunctionParameters` - - `"container_file_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. - - `FilePath object { file_id, index, type }` + Omitting `parameters` defines a function with an empty parameter list. - A path to a file. + - `strict: optional boolean` - - `file_id: 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 ID of the file. + - `type: "function"` - - `index: number` + The type of tool being defined: `function` - The index of the file in the list of files. + - `"function"` - - `type: "file_path"` + - `truncation_strategy: object { type, last_messages }` - The type of the file path. Always `file_path`. + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `"file_path"` + - `type: "auto" or "last_messages"` - - `text: string` + 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 text output from the model. + - `"auto"` - - `type: "output_text"` + - `"last_messages"` - The type of the output text. Always `output_text`. + - `last_messages: optional number` - - `"output_text"` + The number of most recent messages from the thread when constructing the context for the run. - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - - `token: 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.). - - `bytes: array of number` + - `completion_tokens: number` - - `logprob: number` + Number of completion tokens used over the course of the run. - - `top_logprobs: array of object { token, bytes, logprob }` + - `prompt_tokens: number` - - `token: string` + Number of prompt tokens used over the course of the run. - - `bytes: array of number` + - `total_tokens: number` - - `logprob: number` + Total number of tokens used (prompt + completion). - - `BetaResponseOutputRefusal object { refusal, type }` + - `temperature: optional number` - A refusal from the model. + The sampling temperature used for this run. If not set, defaults to 1. - - `refusal: string` + - `top_p: optional number` - The refusal explanation from the model. + The nucleus sampling value used for this run. If not set, defaults to 1. - - `type: "refusal"` +### Example - The type of the refusal. Always `refusal`. +```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 '{}' +``` - - `"refusal"` +#### Response - - `role: "assistant"` +```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 role of the output message. Always `assistant`. +### Example - - `"assistant"` +```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" + } + }' +``` - - `status: "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 +{ + "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 +} +``` - - `"in_progress"` +## Submit tool outputs to run - - `"completed"` +**post** `/threads/{thread_id}/runs/{run_id}/submit_tool_outputs` - - `"incomplete"` +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: "message"` +### Path Parameters - The type of the output message. Always `message`. +- `thread_id: string` - - `"message"` +- `run_id: string` - - `agent: optional object { agent_name }` +### Body Parameters - The agent that produced this item. +- `tool_outputs: array of object { output, tool_call_id }` - - `agent_name: string` + A list of tools for which the outputs are being submitted. - The canonical name of the agent that produced this item. + - `output: optional string` - - `phase: optional "commentary" or "final_answer"` + The output of the tool call to be submitted to continue the run. - 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. + - `tool_call_id: optional string` - - `"commentary"` + The ID of the tool call in the `required_action` object within the run object the output is being submitted for. - - `"final_answer"` +- `stream: optional boolean` - - `FileSearchCall object { id, queries, status, 3 more }` + 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. - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. +### Returns - - `id: string` +- `Run object { id, assistant_id, cancelled_at, 24 more }` - The unique ID of the file search tool call. + Represents an execution run on a [thread](/docs/api-reference/threads). - - `queries: array of string` + - `id: string` - The queries used to search for files. + The identifier, which can be referenced in API endpoints. - - `status: "in_progress" or "searching" or "completed" or 2 more` + - `assistant_id: string` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + The ID of the [assistant](/docs/api-reference/assistants) used for execution of this run. - - `"in_progress"` + - `cancelled_at: number` - - `"searching"` + The Unix timestamp (in seconds) for when the run was cancelled. - - `"completed"` + - `completed_at: number` - - `"incomplete"` + The Unix timestamp (in seconds) for when the run was completed. - - `"failed"` + - `created_at: number` - - `type: "file_search_call"` + The Unix timestamp (in seconds) for when the run was created. - The type of the file search tool call. Always `file_search_call`. + - `expires_at: number` - - `"file_search_call"` + The Unix timestamp (in seconds) for when the run will expire. - - `agent: optional object { agent_name }` + - `failed_at: number` - The agent that produced this item. + The Unix timestamp (in seconds) for when the run failed. - - `agent_name: string` + - `incomplete_details: object { reason }` - The canonical name of the agent that produced this item. + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - - `results: optional array of object { attributes, file_id, filename, 2 more }` + - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` - The results of the file search tool call. + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - - `attributes: optional map[string or number or boolean]` + - `"max_completion_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. Keys are strings - with a maximum length of 64 characters. Values are strings with a maximum - length of 512 characters, booleans, or numbers. + - `"max_prompt_tokens"` - - `string` + - `instructions: string` - - `number` + The instructions that the [assistant](/docs/api-reference/assistants) used for this run. - - `boolean` + - `last_error: object { code, message }` - - `file_id: optional string` + The last error associated with this run. Will be `null` if there are no errors. - The unique ID of the file. + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` - - `filename: optional string` + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - The name of the file. + - `"server_error"` - - `score: optional number` + - `"rate_limit_exceeded"` - The relevance score of the file - a value between 0 and 1. + - `"invalid_prompt"` - - `text: optional string` + - `message: string` - The text that was retrieved from the file. + A human-readable description of the error. - - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` + - `max_completion_tokens: number` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + 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 the computer call. + The maximum number of prompt tokens specified to have been used over the course of the run. - - `call_id: string` + - `metadata: Metadata` - An identifier used when responding to the tool call with 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. - - `pending_safety_checks: array of object { id, code, message }` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The pending safety checks for the computer call. + - `model: string` - - `id: string` + The model that the [assistant](/docs/api-reference/assistants) used for this run. - The ID of the pending safety check. + - `object: "thread.run"` - - `code: optional string` + The object type, which is always `thread.run`. - The type of the pending safety check. + - `"thread.run"` - - `message: optional string` + - `parallel_tool_calls: boolean` - Details about the pending safety check. + Whether to enable [parallel function calling](/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `status: "in_progress" or "completed" or "incomplete"` + - `required_action: object { submit_tool_outputs, type }` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Details on the action required to continue the run. Will be `null` if no action is required. - - `"in_progress"` + - `submit_tool_outputs: object { tool_calls }` - - `"completed"` + Details on the tool outputs needed for this run to continue. - - `"incomplete"` + - `tool_calls: array of RequiredActionFunctionToolCall` - - `type: "computer_call"` + A list of the relevant tool calls. - The type of the computer call. Always `computer_call`. + - `id: string` - - `"computer_call"` + 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. - - `action: optional BetaComputerAction` + - `function: object { arguments, name }` - A click action. + The function definition. - - `Click object { button, type, x, 2 more }` + - `arguments: string` - A click action. + The arguments that the model expects you to pass to the function. - - `button: "left" or "right" or "wheel" or 2 more` + - `name: string` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + The name of the function. - - `"left"` + - `type: "function"` - - `"right"` + The type of tool call the output is required for. For now, this is always `function`. - - `"wheel"` + - `"function"` - - `"back"` + - `type: "submit_tool_outputs"` - - `"forward"` + For now, this is always `submit_tool_outputs`. - - `type: "click"` + - `"submit_tool_outputs"` - Specifies the event type. For a click action, this property is always `click`. + - `response_format: AssistantResponseFormatOption` - - `"click"` + 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`. - - `x: 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 x-coordinate where the click occurred. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `y: 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 y-coordinate where the click occurred. + - `"auto"` - - `keys: optional array of string` + `auto` is the default value - The keys being held while clicking. + - `"auto"` - - `DoubleClick object { keys, type, x, y }` + - `ResponseFormatText object { type }` - A double click action. + Default response format. Used to generate text responses. - - `keys: array of string` + - `type: "text"` - The keys being held while double-clicking. + The type of response format being defined. Always `text`. - - `type: "double_click"` + - `"text"` - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `ResponseFormatJSONObject object { type }` - - `"double_click"` + 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. - - `x: number` + - `type: "json_object"` - The x-coordinate where the double click occurred. + The type of response format being defined. Always `json_object`. - - `y: number` + - `"json_object"` - The y-coordinate where the double click occurred. + - `ResponseFormatJSONSchema object { json_schema, type }` - - `Drag object { path, type, keys }` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - A drag action. + - `json_schema: object { name, description, schema, strict }` - - `path: array of object { x, y }` + Structured Outputs configuration options, including a JSON Schema. - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `name: string` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - - `x: number` + - `description: optional string` - The x-coordinate. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `y: number` + - `schema: optional map[unknown]` - The y-coordinate. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `type: "drag"` + - `strict: optional boolean` - Specifies the event type. For a drag action, this property is always set to `drag`. + 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). - - `"drag"` + - `type: "json_schema"` - - `keys: optional array of string` + The type of response format being defined. Always `json_schema`. - The keys being held while dragging the mouse. + - `"json_schema"` - - `Keypress object { keys, type }` + - `started_at: number` - A collection of keypresses the model would like to perform. + The Unix timestamp (in seconds) for when the run was started. - - `keys: array of string` + - `status: "queued" or "in_progress" or "requires_action" or 6 more` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - - `type: "keypress"` + - `"queued"` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `"in_progress"` - - `"keypress"` + - `"requires_action"` - - `Move object { type, x, y, keys }` + - `"cancelling"` - A mouse move action. + - `"cancelled"` - - `type: "move"` + - `"failed"` - Specifies the event type. For a move action, this property is always set to `move`. + - `"completed"` - - `"move"` + - `"incomplete"` - - `x: number` + - `"expired"` - The x-coordinate to move to. + - `thread_id: string` - - `y: number` + The ID of the [thread](/docs/api-reference/threads) that was executed on as a part of this run. - The y-coordinate to move to. + - `tool_choice: AssistantToolChoiceOption` - - `keys: 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. - The keys being held while moving the mouse. + - `"none" or "auto" or "required"` - - `Screenshot object { type }` + `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. - A screenshot action. + - `"none"` - - `type: "screenshot"` + - `"auto"` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `"required"` - - `"screenshot"` + - `AssistantToolChoice object { type, function }` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + Specifies a tool the model should use. Use to force the model to call a specific tool. - A scroll action. + - `type: "function" or "code_interpreter" or "file_search"` - - `scroll_x: number` + The type of the tool. If type is `function`, the function name must be set - The horizontal scroll distance. + - `"function"` - - `scroll_y: number` + - `"code_interpreter"` - The vertical scroll distance. + - `"file_search"` - - `type: "scroll"` + - `function: optional AssistantToolChoiceFunction` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `name: string` - - `"scroll"` + The name of the function to call. - - `x: number` + - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool` - The x-coordinate where the scroll occurred. + The list of tools that the [assistant](/docs/api-reference/assistants) used for this run. - - `y: number` + - `CodeInterpreterTool object { type }` - The y-coordinate where the scroll occurred. + - `type: "code_interpreter"` - - `keys: optional array of string` + The type of tool being defined: `code_interpreter` - The keys being held while scrolling. + - `"code_interpreter"` - - `Type object { text, type }` + - `FileSearchTool object { type, file_search }` - An action to type in text. + - `type: "file_search"` - - `text: string` + The type of tool being defined: `file_search` - The text to type. + - `"file_search"` - - `type: "type"` + - `file_search: optional object { max_num_results, ranking_options }` - Specifies the event type. For a type action, this property is always set to `type`. + Overrides for the file search tool. - - `"type"` + - `max_num_results: optional number` - - `Wait 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 wait 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. - - `type: "wait"` + - `ranking_options: optional object { score_threshold, ranker }` - Specifies the event type. For a wait action, this property is always set to `wait`. + 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. - - `"wait"` + See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `actions: optional BetaComputerActionList` + - `score_threshold: number` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `Click object { button, type, x, 2 more }` + - `ranker: optional "auto" or "default_2024_08_21"` - A click action. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `DoubleClick object { keys, type, x, y }` + - `"auto"` - A double click action. + - `"default_2024_08_21"` - - `Drag object { path, type, keys }` + - `FunctionTool object { function, type }` - A drag action. + - `function: FunctionDefinition` - - `Keypress object { keys, type }` + - `name: string` - A collection of keypresses the model would like to perform. + 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. - - `Move object { type, x, y, keys }` + - `description: optional string` - A mouse move action. + A description of what the function does, used by the model to choose when and how to call the function. - - `Screenshot object { type }` + - `parameters: optional FunctionParameters` - A screenshot action. + 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. - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + Omitting `parameters` defines a function with an empty parameter list. - A scroll action. + - `strict: optional boolean` - - `Type object { text, 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). - An action to type in text. + - `type: "function"` - - `Wait object { type }` + The type of tool being defined: `function` - A wait action. + - `"function"` - - `agent: optional object { agent_name }` + - `truncation_strategy: object { type, last_messages }` - The agent that produced this item. + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `agent_name: string` + - `type: "auto" or "last_messages"` - The canonical name of the agent that produced this item. + 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`. - - `ComputerCallOutput object { call_id, output, type, 4 more }` + - `"auto"` - The output of a computer tool call. + - `"last_messages"` - - `call_id: string` + - `last_messages: optional number` - The ID of the computer tool call that produced the output. + The number of most recent messages from the thread when constructing the context for the run. - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - A computer screenshot image used with the computer use tool. + 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.). - - `type: "computer_screenshot"` + - `completion_tokens: number` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + Number of completion tokens used over the course of the run. - - `"computer_screenshot"` + - `prompt_tokens: number` - - `file_id: optional string` + Number of prompt tokens used over the course of the run. - The identifier of an uploaded file that contains the screenshot. + - `total_tokens: number` - - `image_url: optional string` + Total number of tokens used (prompt + completion). - The URL of the screenshot image. + - `temperature: optional number` - - `type: "computer_call_output"` + The sampling temperature used for this run. If not set, defaults to 1. - The type of the computer tool call output. Always `computer_call_output`. + - `top_p: optional number` - - `"computer_call_output"` + The nucleus sampling value used for this run. If not set, defaults to 1. - - `id: optional string` +### Example - The ID of the computer tool call output. +```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": [ + {} + ] + }' +``` - - `acknowledged_safety_checks: optional array of object { id, code, message }` +#### Response - The safety checks reported by the API that have been acknowledged by the developer. +```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 +} +``` - - `id: string` +### Example - The ID of the pending safety check. +```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." + } + ] + }' +``` - - `code: optional string` +#### Response - The type of the pending safety check. +```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 +} +``` - - `message: optional string` +### Streaming - Details about the pending safety check. +```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 + }' +``` - - `agent: optional object { agent_name }` +#### Response - The agent that produced this item. +```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}} - - `agent_name: 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 canonical name of the agent that produced this item. +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}} - - `status: optional "in_progress" or "completed" or "incomplete"` +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 status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. +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} - - `"in_progress"` +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":{}} - - `"completed"` +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":{}} - - `"incomplete"` +event: thread.message.delta +data: {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"The","annotations":[]}}]}} - - `WebSearchCall object { id, action, status, 2 more }` +event: thread.message.delta +data: {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" current"}}]}} - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. +event: thread.message.delta +data: {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" weather"}}]}} - - `id: string` +... - The unique ID of the web search tool call. +event: thread.message.delta +data: {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" sunny"}}]}} - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` +event: thread.message.delta +data: {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"."}}]}} - 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). +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":{}} - - `Search object { type, queries, query, sources }` +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}} - Action type "search" - Performs a web search query. +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}} - - `type: "search"` +event: done +data: [DONE] +``` - The action type. +## Cancel a run - - `"search"` +**post** `/threads/{thread_id}/runs/{run_id}/cancel` - - `queries: optional array of string` +Cancels a run that is `in_progress`. - The search queries. +### Path Parameters - - `query: optional string` +- `thread_id: string` - The search query. +- `run_id: string` - - `sources: optional array of object { type, url }` +### Returns - The sources used in the search. +- `Run object { id, assistant_id, cancelled_at, 24 more }` - - `type: "url"` + Represents an execution run on a [thread](/docs/api-reference/threads). - The type of source. Always `url`. + - `id: string` - - `"url"` + The identifier, which can be referenced in API endpoints. - - `url: string` + - `assistant_id: string` - The URL of the source. + The ID of the [assistant](/docs/api-reference/assistants) used for execution of this run. - - `OpenPage object { type, url }` + - `cancelled_at: number` - Action type "open_page" - Opens a specific URL from search results. + The Unix timestamp (in seconds) for when the run was cancelled. - - `type: "open_page"` + - `completed_at: number` - The action type. + The Unix timestamp (in seconds) for when the run was completed. - - `"open_page"` + - `created_at: number` - - `url: optional string` + The Unix timestamp (in seconds) for when the run was created. - The URL opened by the model. + - `expires_at: number` - - `FindInPage object { pattern, type, url }` + The Unix timestamp (in seconds) for when the run will expire. - Action type "find_in_page": Searches for a pattern within a loaded page. + - `failed_at: number` - - `pattern: string` + The Unix timestamp (in seconds) for when the run failed. - The pattern or text to search for within the page. + - `incomplete_details: object { reason }` - - `type: "find_in_page"` + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - The action type. + - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` - - `"find_in_page"` + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - - `url: string` + - `"max_completion_tokens"` - The URL of the page searched for the pattern. + - `"max_prompt_tokens"` - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `instructions: string` - The status of the web search tool call. + The instructions that the [assistant](/docs/api-reference/assistants) used for this run. - - `"in_progress"` + - `last_error: object { code, message }` - - `"searching"` + The last error associated with this run. Will be `null` if there are no errors. - - `"completed"` + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` - - `"failed"` + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - - `type: "web_search_call"` + - `"server_error"` - The type of the web search tool call. Always `web_search_call`. + - `"rate_limit_exceeded"` - - `"web_search_call"` + - `"invalid_prompt"` - - `agent: optional object { agent_name }` + - `message: string` - The agent that produced this item. + A human-readable description of the error. - - `agent_name: string` + - `max_completion_tokens: number` - The canonical name of the agent that produced this item. + The maximum number of completion tokens specified to have been used over the course of the run. - - `FunctionCall object { arguments, call_id, name, 6 more }` + - `max_prompt_tokens: number` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + The maximum number of prompt tokens specified to have been used over the course of the run. - - `arguments: string` + - `metadata: Metadata` - A JSON string of the arguments to pass to the 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. - - `call_id: string` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The unique ID of the function tool call generated by the model. + - `model: string` - - `name: string` + The model that the [assistant](/docs/api-reference/assistants) used for this run. - The name of the function to run. + - `object: "thread.run"` - - `type: "function_call"` + The object type, which is always `thread.run`. - The type of the function tool call. Always `function_call`. + - `"thread.run"` - - `"function_call"` + - `parallel_tool_calls: boolean` - - `id: optional string` + Whether to enable [parallel function calling](/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - The unique ID of the function tool call. + - `required_action: object { submit_tool_outputs, type }` - - `agent: optional object { agent_name }` + Details on the action required to continue the run. Will be `null` if no action is required. - The agent that produced this item. + - `submit_tool_outputs: object { tool_calls }` - - `agent_name: string` + Details on the tool outputs needed for this run to continue. - The canonical name of the agent that produced this item. + - `tool_calls: array of RequiredActionFunctionToolCall` - - `caller: optional object { type } or object { caller_id, type }` + A list of the relevant tool calls. - The execution context that produced this tool call. + - `id: string` - - `Direct object { 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. - - `type: "direct"` + - `function: object { arguments, name }` - - `"direct"` + The function definition. - - `Program object { caller_id, type }` + - `arguments: string` - - `caller_id: string` + The arguments that the model expects you to pass to the function. - The call ID of the program item that produced this tool call. + - `name: string` - - `type: "program"` + The name of the function. - - `"program"` + - `type: "function"` - - `namespace: optional string` + The type of tool call the output is required for. For now, this is always `function`. - The namespace of the function to run. + - `"function"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `type: "submit_tool_outputs"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + For now, this is always `submit_tool_outputs`. - - `"in_progress"` + - `"submit_tool_outputs"` - - `"completed"` + - `response_format: AssistantResponseFormatOption` - - `"incomplete"` + 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`. - - `FunctionCallOutput object { call_id, output, type, 4 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 output of a function tool call. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `call_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. - The unique ID of the function tool call generated by the model. + - `"auto"` - - `output: string or BetaResponseFunctionCallOutputItemList` + `auto` is the default value - Text, image, or file output of the function tool call. + - `"auto"` - - `string` + - `ResponseFormatText object { type }` - A JSON string of the output of the function tool call. + Default response format. Used to generate text responses. - - `BetaResponseFunctionCallOutputItemList = array of BetaResponseFunctionCallOutputItem` + - `type: "text"` - An array of content outputs (text, image, file) for the function tool call. + The type of response format being defined. Always `text`. - - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` + - `"text"` - A text input to the model. + - `ResponseFormatJSONObject object { type }` - - `text: 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. - The text input to the model. + - `type: "json_object"` - - `type: "input_text"` + The type of response format being defined. Always `json_object`. - The type of the input item. Always `input_text`. + - `"json_object"` - - `"input_text"` + - `ResponseFormatJSONSchema object { json_schema, type }` - - `prompt_cache_breakpoint: optional object { mode }` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `json_schema: object { name, description, schema, strict }` - - `mode: "explicit"` + Structured Outputs configuration options, including a JSON Schema. - The breakpoint mode. Always `explicit`. + - `name: string` - - `"explicit"` + 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. - - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` + - `description: optional string` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `type: "input_image"` + - `schema: optional map[unknown]` - The type of the input item. Always `input_image`. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `"input_image"` + - `strict: optional boolean` - - `detail: optional "low" or "high" or "auto" or "original"` + 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 detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `type: "json_schema"` - - `"low"` + The type of response format being defined. Always `json_schema`. - - `"high"` + - `"json_schema"` - - `"auto"` + - `started_at: number` - - `"original"` + The Unix timestamp (in seconds) for when the run was started. - - `file_id: optional string` + - `status: "queued" or "in_progress" or "requires_action" or 6 more` - The ID of the file to be sent to the model. + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - - `image_url: optional string` + - `"queued"` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `"in_progress"` - - `prompt_cache_breakpoint: optional object { mode }` + - `"requires_action"` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `"cancelling"` - - `mode: "explicit"` + - `"cancelled"` - The breakpoint mode. Always `explicit`. + - `"failed"` - - `"explicit"` + - `"completed"` - - `BetaResponseInputFileContent object { type, detail, file_data, 4 more }` + - `"incomplete"` - A file input to the model. + - `"expired"` - - `type: "input_file"` + - `thread_id: string` - The type of the input item. Always `input_file`. + The ID of the [thread](/docs/api-reference/threads) that was executed on as a part of this run. - - `"input_file"` + - `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. - 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`. + - `"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"` - - `file_data: optional string` + - `"required"` - The base64-encoded data of the file to be sent to the model. + - `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 file to be sent to the model. + - `type: "function" or "code_interpreter" or "file_search"` - - `file_url: optional string` + The type of the tool. If type is `function`, the function name must be set - The URL of the file to be sent to the model. + - `"function"` - - `filename: optional string` + - `"code_interpreter"` - The name of the file to be sent to the model. + - `"file_search"` - - `prompt_cache_breakpoint: optional object { mode }` + - `function: optional AssistantToolChoiceFunction` - Marks the exact end of a reusable 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 function to call. - The breakpoint mode. Always `explicit`. + - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool` - - `"explicit"` + The list of tools that the [assistant](/docs/api-reference/assistants) used for this run. - - `type: "function_call_output"` + - `CodeInterpreterTool object { type }` - The type of the function tool call output. Always `function_call_output`. + - `type: "code_interpreter"` - - `"function_call_output"` + The type of tool being defined: `code_interpreter` - - `id: optional string` + - `"code_interpreter"` - The unique ID of the function tool call output. Populated when this item is returned via API. + - `FileSearchTool object { type, file_search }` - - `agent: optional object { agent_name }` + - `type: "file_search"` - The agent that produced this item. + The type of tool being defined: `file_search` - - `agent_name: string` + - `"file_search"` - The canonical name of the agent that produced this item. + - `file_search: optional object { max_num_results, ranking_options }` - - `caller: optional object { type } or object { caller_id, type }` + Overrides for the file search tool. - The execution context that produced this tool call. + - `max_num_results: optional number` - - `Direct 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. - - `type: "direct"` + 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 caller type. Always `direct`. + - `ranking_options: optional object { score_threshold, ranker }` - - `"direct"` + 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. - - `Program object { caller_id, type }` + See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `caller_id: string` + - `score_threshold: number` - The call ID of the program item that produced this tool call. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `type: "program"` + - `ranker: optional "auto" or "default_2024_08_21"` - The caller type. Always `program`. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `"program"` + - `"auto"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"default_2024_08_21"` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + - `FunctionTool object { function, type }` - - `"in_progress"` + - `function: FunctionDefinition` - - `"completed"` + - `name: string` - - `"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. - - `AgentMessage object { author, content, recipient, 3 more }` + - `description: optional string` - A message routed between agents. + A description of what the function does, used by the model to choose when and how to call the function. - - `author: string` + - `parameters: optional FunctionParameters` - The sending agent identity. + 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. - - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` + Omitting `parameters` defines a function with an empty parameter list. - Plaintext, image, or encrypted content sent between agents. + - `strict: optional boolean` - - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` + 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). - A text input to the model. + - `type: "function"` - - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` + The type of tool being defined: `function` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `"function"` - - `EncryptedContent object { encrypted_content, type }` + - `truncation_strategy: object { type, last_messages }` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `encrypted_content: string` + - `type: "auto" or "last_messages"` - Opaque encrypted content. + 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: "encrypted_content"` + - `"auto"` - The type of the input item. Always `encrypted_content`. + - `"last_messages"` - - `"encrypted_content"` + - `last_messages: optional number` - - `recipient: string` + The number of most recent messages from the thread when constructing the context for the run. - The destination agent identity. + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - - `type: "agent_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 item type. Always `agent_message`. + - `completion_tokens: number` - - `"agent_message"` + Number of completion tokens used over the course of the run. - - `id: optional string` + - `prompt_tokens: number` - The unique ID of this agent message item. + Number of prompt tokens used over the course of the run. - - `agent: optional object { agent_name }` + - `total_tokens: number` - The agent that produced this item. + Total number of tokens used (prompt + completion). - - `agent_name: string` + - `temperature: optional number` - The canonical name of the agent that produced this item. + The sampling temperature used for this run. If not set, defaults to 1. - - `MultiAgentCall object { action, arguments, call_id, 3 more }` + - `top_p: optional number` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + The nucleus sampling value used for this run. If not set, defaults to 1. - The multi-agent action that was executed. +### Example - - `"spawn_agent"` +```http +curl https://api.openai.com/v1/threads/$THREAD_ID/runs/$RUN_ID/cancel \ + -X POST \ + -H 'OpenAI-Beta: assistants=v2' \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - - `"interrupt_agent"` +#### Response - - `"list_agents"` +```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 +} +``` - - `"send_message"` +### Example - - `"followup_task"` +```http +curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/cancel \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "OpenAI-Beta: assistants=v2" \ + -X POST +``` - - `"wait_agent"` +#### Response - - `arguments: string` +```json +{ + "id": "run_abc123", + "object": "thread.run", + "created_at": 1699076126, + "assistant_id": "asst_abc123", + "thread_id": "thread_abc123", + "status": "cancelling", + "started_at": 1699076126, + "expires_at": 1699076726, + "cancelled_at": null, + "failed_at": null, + "completed_at": null, + "last_error": null, + "model": "gpt-4o", + "instructions": "You summarize books.", + "tools": [ + { + "type": "file_search" + } + ], + "tool_resources": { + "file_search": { + "vector_store_ids": ["vs_123"] + } + }, + "metadata": {}, + "usage": null, + "temperature": 1.0, + "top_p": 1.0, + "response_format": "auto", + "tool_choice": "auto", + "parallel_tool_calls": true +} +``` - The action arguments as a JSON string. +## Domain Types - - `call_id: string` +### Required Action Function Tool Call - The unique ID linking this call to its output. +- `RequiredActionFunctionToolCall object { id, function, type }` - - `type: "multi_agent_call"` + Tool call objects - The item type. Always `multi_agent_call`. + - `id: string` - - `"multi_agent_call"` + 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. - - `id: optional string` + - `function: object { arguments, name }` - The unique ID of this multi-agent call. + The function definition. - - `agent: optional object { agent_name }` + - `arguments: string` - The agent that produced this item. + The arguments that the model expects you to pass to the function. - - `agent_name: string` + - `name: string` - The canonical name of the agent that produced this item. + The name of the function. - - `MultiAgentCallOutput object { action, call_id, output, 3 more }` + - `type: "function"` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + The type of tool call the output is required for. For now, this is always `function`. - The multi-agent action that produced this result. + - `"function"` - - `"spawn_agent"` +### Run - - `"interrupt_agent"` +- `Run object { id, assistant_id, cancelled_at, 24 more }` - - `"list_agents"` + Represents an execution run on a [thread](/docs/api-reference/threads). - - `"send_message"` + - `id: string` - - `"followup_task"` + The identifier, which can be referenced in API endpoints. - - `"wait_agent"` + - `assistant_id: string` - - `call_id: string` + The ID of the [assistant](/docs/api-reference/assistants) used for execution of this run. - The unique ID of the multi-agent call. + - `cancelled_at: number` - - `output: array of object { text, type, annotations }` + The Unix timestamp (in seconds) for when the run was cancelled. - Text output returned by the multi-agent action. + - `completed_at: number` - - `text: string` + The Unix timestamp (in seconds) for when the run was completed. - The text content. + - `created_at: number` - - `type: "output_text"` + The Unix timestamp (in seconds) for when the run was created. - The content type. Always `output_text`. + - `expires_at: number` - - `"output_text"` + The Unix timestamp (in seconds) for when the run will expire. - - `annotations: optional array of object { file_id, filename, index, type } or array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` + - `failed_at: number` - Citations associated with the text content. + The Unix timestamp (in seconds) for when the run failed. - - `array of object { file_id, filename, index, type }` + - `incomplete_details: object { reason }` - - `file_id: string` + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - The ID of the file. + - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` - - `filename: 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 filename of the file cited. + - `"max_completion_tokens"` - - `index: number` + - `"max_prompt_tokens"` - The index of the file in the list of files. + - `instructions: string` - - `type: "file_citation"` + The instructions that the [assistant](/docs/api-reference/assistants) used for this run. - The citation type. Always `file_citation`. + - `last_error: object { code, message }` - - `"file_citation"` + The last error associated with this run. Will be `null` if there are no errors. - - `array of object { end_index, start_index, title, 2 more }` + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` - - `end_index: number` + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - The index of the last character of the citation in the message. + - `"server_error"` - - `start_index: number` + - `"rate_limit_exceeded"` - The index of the first character of the citation in the message. + - `"invalid_prompt"` - - `title: string` + - `message: string` - The title of the cited resource. + A human-readable description of the error. - - `type: "url_citation"` + - `max_completion_tokens: number` - The citation type. Always `url_citation`. + The maximum number of completion tokens specified to have been used over the course of the run. - - `"url_citation"` + - `max_prompt_tokens: number` - - `url: string` + The maximum number of prompt tokens specified to have been used over the course of the run. - The URL of the cited resource. + - `metadata: Metadata` - - `array of 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. + - `model: string` - - `end_index: number` + The model that the [assistant](/docs/api-reference/assistants) used for this run. - The index of the last character of the citation in the message. + - `object: "thread.run"` - - `file_id: string` + The object type, which is always `thread.run`. - The ID of the container file. + - `"thread.run"` - - `filename: string` + - `parallel_tool_calls: boolean` - The filename of the container file cited. + Whether to enable [parallel function calling](/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `start_index: number` + - `required_action: object { submit_tool_outputs, type }` - The index of the first character of the citation in the message. + Details on the action required to continue the run. Will be `null` if no action is required. - - `type: "container_file_citation"` + - `submit_tool_outputs: object { tool_calls }` - The citation type. Always `container_file_citation`. + Details on the tool outputs needed for this run to continue. - - `"container_file_citation"` + - `tool_calls: array of RequiredActionFunctionToolCall` - - `type: "multi_agent_call_output"` + A list of the relevant tool calls. - The item type. Always `multi_agent_call_output`. + - `id: string` - - `"multi_agent_call_output"` + 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. - - `id: optional string` + - `function: object { arguments, name }` - The unique ID of this multi-agent call output. + The function definition. - - `agent: optional object { agent_name }` + - `arguments: string` - The agent that produced this item. + The arguments that the model expects you to pass to the function. - - `agent_name: string` + - `name: string` - The canonical name of the agent that produced this item. + The name of the function. - - `ToolSearchCall object { arguments, type, id, 4 more }` + - `type: "function"` - - `arguments: unknown` + The type of tool call the output is required for. For now, this is always `function`. - The arguments supplied to the tool search call. + - `"function"` - - `type: "tool_search_call"` + - `type: "submit_tool_outputs"` - The item type. Always `tool_search_call`. + For now, this is always `submit_tool_outputs`. - - `"tool_search_call"` + - `"submit_tool_outputs"` - - `id: optional string` + - `response_format: AssistantResponseFormatOption` - The unique ID of this tool search call. + 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`. - - `agent: optional object { agent_name }` + 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 agent that produced this item. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `agent_name: 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 canonical name of the agent that produced this item. + - `"auto"` - - `call_id: optional string` + `auto` is the default value - The unique ID of the tool search call generated by the model. + - `"auto"` - - `execution: optional "server" or "client"` + - `ResponseFormatText object { type }` - Whether tool search was executed by the server or by the client. + Default response format. Used to generate text responses. - - `"server"` + - `type: "text"` - - `"client"` + The type of response format being defined. Always `text`. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"text"` - The status of the tool search call. + - `ResponseFormatJSONObject object { type }` - - `"in_progress"` + 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. - - `"completed"` + - `type: "json_object"` - - `"incomplete"` + The type of response format being defined. Always `json_object`. - - `ToolSearchOutput object { tools, type, id, 4 more }` + - `"json_object"` - - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` + - `ResponseFormatJSONSchema object { json_schema, type }` - The loaded tool definitions returned by the tool search output. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - - `Function object { name, parameters, strict, 5 more }` + - `json_schema: object { name, description, schema, strict }` - 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). + Structured Outputs configuration options, including a JSON Schema. - `name: string` - The name of the function to call. - - - `parameters: map[unknown]` + 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 JSON schema object describing the parameters of the function. + - `description: optional string` - - `strict: boolean` + A description of what the response format is for, used by the model to + determine how to respond in the format. - Whether strict parameter validation is enforced for this function tool. + - `schema: optional map[unknown]` - - `type: "function"` + 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 function tool. Always `function`. + - `strict: optional boolean` - - `"function"` + 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). - - `allowed_callers: optional array of "direct" or "programmatic"` + - `type: "json_schema"` - The tool invocation context(s). + The type of response format being defined. Always `json_schema`. - - `"direct"` + - `"json_schema"` - - `"programmatic"` + - `started_at: number` - - `defer_loading: optional boolean` + The Unix timestamp (in seconds) for when the run was started. - Whether this function is deferred and loaded via tool search. + - `status: "queued" or "in_progress" or "requires_action" or 6 more` - - `description: optional string` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - A description of the function. Used by the model to determine whether or not to call the function. + - `"queued"` - - `output_schema: optional map[unknown]` + - `"in_progress"` - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `"requires_action"` - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + - `"cancelling"` - 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). + - `"cancelled"` - - `type: "file_search"` + - `"failed"` - The type of the file search tool. Always `file_search`. + - `"completed"` - - `"file_search"` + - `"incomplete"` - - `vector_store_ids: array of string` + - `"expired"` - The IDs of the vector stores to search. + - `thread_id: string` - - `filters: optional object { key, type, value } or object { filters, type }` + The ID of the [thread](/docs/api-reference/threads) that was executed on as a part of this run. - A filter to apply. + - `tool_choice: AssistantToolChoiceOption` - - `ComparisonFilter object { key, type, value }` + 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 filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `"none" or "auto" or "required"` - - `key: string` + `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 key to compare against the value. + - `"none"` - - `type: "eq" or "ne" or "gt" or 5 more` + - `"auto"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `"required"` - - `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 + - `AssistantToolChoice object { type, function }` - - `"eq"` + Specifies a tool the model should use. Use to force the model to call a specific tool. - - `"ne"` + - `type: "function" or "code_interpreter" or "file_search"` - - `"gt"` + The type of the tool. If type is `function`, the function name must be set - - `"gte"` + - `"function"` - - `"lt"` + - `"code_interpreter"` - - `"lte"` + - `"file_search"` - - `"in"` + - `function: optional AssistantToolChoiceFunction` - - `"nin"` + - `name: string` - - `value: string or number or boolean or array of string or number` + The name of the function to call. - The value to compare against the attribute key; supports string, number, or boolean types. + - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool` - - `string` + The list of tools that the [assistant](/docs/api-reference/assistants) used for this run. - - `number` + - `CodeInterpreterTool object { type }` - - `boolean` + - `type: "code_interpreter"` - - `array of string or number` + The type of tool being defined: `code_interpreter` - - `string` + - `"code_interpreter"` - - `number` + - `FileSearchTool object { type, file_search }` - - `CompoundFilter object { filters, type }` + - `type: "file_search"` - Combine multiple filters using `and` or `or`. + The type of tool being defined: `file_search` - - `filters: array of object { key, type, value } or unknown` + - `"file_search"` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `file_search: optional object { max_num_results, ranking_options }` - - `ComparisonFilter object { key, type, value }` + Overrides for the file search tool. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `max_num_results: optional number` - - `key: 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 key to compare against the value. + 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: "eq" or "ne" or "gt" or 5 more` + - `ranking_options: optional object { score_threshold, ranker }` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + 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. - - `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 + See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `"eq"` + - `score_threshold: number` - - `"ne"` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `"gt"` + - `ranker: optional "auto" or "default_2024_08_21"` - - `"gte"` + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `"lt"` + - `"auto"` - - `"lte"` + - `"default_2024_08_21"` - - `"in"` + - `FunctionTool object { function, type }` - - `"nin"` + - `function: FunctionDefinition` - - `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 function to be called. 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 function does, used by the model to choose when and how to call the function. - - `boolean` + - `parameters: optional FunctionParameters` - - `array of string or 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. - - `string` + Omitting `parameters` defines a function with an empty parameter list. - - `number` + - `strict: optional boolean` - - `unknown` + 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: "and" or "or"` + - `type: "function"` - Type of operation: `and` or `or`. + The type of tool being defined: `function` - - `"and"` + - `"function"` - - `"or"` + - `truncation_strategy: object { type, last_messages }` - - `max_num_results: 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. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `type: "auto" or "last_messages"` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + 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`. - Ranking options for search. + - `"auto"` - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `"last_messages"` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `last_messages: optional number` - - `embedding_weight: number` + The number of most recent messages from the thread when constructing the context for the run. - The weight of the embedding in the reciprocal ranking fusion. + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - - `text_weight: 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 weight of the text in the reciprocal ranking fusion. + - `completion_tokens: number` - - `ranker: optional "auto" or "default-2024-11-15"` + Number of completion tokens used over the course of the run. - The ranker to use for the file search. + - `prompt_tokens: number` - - `"auto"` + Number of prompt tokens used over the course of the run. - - `"default-2024-11-15"` + - `total_tokens: number` - - `score_threshold: optional number` + Total number of tokens used (prompt + completion). - 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. + - `temperature: optional number` - - `Computer object { type }` + The sampling temperature used for this run. If not set, defaults to 1. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `top_p: optional number` - - `type: "computer"` + The nucleus sampling value used for this run. If not set, defaults to 1. - The type of the computer tool. Always `computer`. +# Steps - - `"computer"` +## List run steps - - `ComputerUsePreview object { display_height, display_width, environment, type }` +**get** `/threads/{thread_id}/runs/{run_id}/steps` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). +Returns a list of run steps belonging to a run. - - `display_height: number` +### Path Parameters - The height of the computer display. +- `thread_id: string` - - `display_width: number` +- `run_id: string` - The width of the computer display. +### Query Parameters - - `environment: "windows" or "mac" or "linux" or 2 more` +- `after: optional string` - The type of computer environment to control. + 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. - - `"windows"` +- `before: optional string` - - `"mac"` + 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. - - `"linux"` +- `include: optional array of RunStepInclude` - - `"ubuntu"` + 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. - - `"browser"` + See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `type: "computer_use_preview"` + - `"step_details.tool_calls[*].file_search.results[*].content"` - The type of the computer use tool. Always `computer_use_preview`. +- `limit: optional number` - - `"computer_use_preview"` + A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. - - `WebSearch object { type, filters, search_context_size, user_location }` +- `order: optional "asc" or "desc"` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. - - `type: "web_search" or "web_search_2025_08_26"` + - `"asc"` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `"desc"` - - `"web_search"` +### Returns - - `"web_search_2025_08_26"` +- `data: array of RunStep` - - `filters: optional object { allowed_domains }` + - `id: string` - Filters for the search. + The identifier of the run step, which can be referenced in API endpoints. - - `allowed_domains: optional array of string` + - `assistant_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 [assistant](/docs/api-reference/assistants) associated with the run step. - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `cancelled_at: number` - - `search_context_size: optional "low" or "medium" or "high"` + The Unix timestamp (in seconds) for when the run step was cancelled. - 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_at: number` - - `"low"` + The Unix timestamp (in seconds) for when the run step completed. - - `"medium"` + - `created_at: number` - - `"high"` + The Unix timestamp (in seconds) for when the run step was created. - - `user_location: optional object { city, country, region, 2 more }` + - `expired_at: number` - The approximate location of the user. + The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. - - `city: optional string` + - `failed_at: number` - Free text input for the city of the user, e.g. `San Francisco`. + The Unix timestamp (in seconds) for when the run step failed. - - `country: optional string` + - `last_error: object { code, message }` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The last error associated with this run step. Will be `null` if there are no errors. - - `region: optional string` + - `code: "server_error" or "rate_limit_exceeded"` - Free text input for the region of the user, e.g. `California`. + One of `server_error` or `rate_limit_exceeded`. - - `timezone: optional string` + - `"server_error"` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `"rate_limit_exceeded"` - - `type: optional "approximate"` + - `message: string` - The type of location approximation. Always `approximate`. + A human-readable description of the error. - - `"approximate"` + - `metadata: Metadata` - - `Mcp object { server_label, type, allowed_callers, 9 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. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `server_label: string` + - `object: "thread.run.step"` - A label for this MCP server, used to identify it in tool calls. + The object type, which is always `thread.run.step`. - - `type: "mcp"` + - `"thread.run.step"` - The type of the MCP tool. Always `mcp`. + - `run_id: string` - - `"mcp"` + The ID of the [run](/docs/api-reference/runs) that this run step is a part of. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `status: "in_progress" or "cancelled" or "failed" or 2 more` - The tool invocation context(s). + The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. - - `"direct"` + - `"in_progress"` - - `"programmatic"` + - `"cancelled"` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + - `"failed"` - List of allowed tool names or a filter object. + - `"completed"` - - `McpAllowedTools = array of string` + - `"expired"` - A string array of allowed tool names + - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` - - `McpToolFilter object { read_only, tool_names }` + The details of the run step. - A filter object to specify which tools are allowed. + - `MessageCreationStepDetails object { message_creation, type }` - - `read_only: optional boolean` + Details of the message creation by the run step. - 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_creation: object { message_id }` - - `tool_names: optional array of string` + - `message_id: string` - List of allowed tool names. + The ID of the message that was created by this run step. - - `authorization: optional string` + - `type: "message_creation"` - 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. + Always `message_creation`. - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + - `"message_creation"` - 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + - `ToolCallsStepDetails object { tool_calls, type }` - Currently supported `connector_id` values are: + Details of the tool 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` + - `tool_calls: array of CodeInterpreterToolCall or FileSearchToolCall or FunctionToolCall` - - `"connector_dropbox"` + 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`. - - `"connector_gmail"` + - `CodeInterpreterToolCall object { id, code_interpreter, type }` - - `"connector_googlecalendar"` + Details of the Code Interpreter tool call the run step was involved in. - - `"connector_googledrive"` + - `id: string` - - `"connector_microsoftteams"` + The ID of the tool call. - - `"connector_outlookcalendar"` + - `code_interpreter: object { input, outputs }` - - `"connector_outlookemail"` + The Code Interpreter tool call definition. - - `"connector_sharepoint"` + - `input: string` - - `defer_loading: optional boolean` + The input to the Code Interpreter tool call. - Whether this MCP tool is deferred and discovered via tool search. + - `outputs: array of object { logs, type } or object { image, type }` - - `headers: optional map[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. - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `CodeInterpreterLogOutput object { logs, type }` - - `require_approval: optional object { always, never } or "always" or "never"` + Text output from the Code Interpreter tool call as part of a run step. - Specify which of the MCP server's tools require approval. + - `logs: string` - - `McpToolApprovalFilter object { always, never }` + The text output from the Code Interpreter 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. + - `type: "logs"` - - `always: optional object { read_only, tool_names }` + Always `logs`. - A filter object to specify which tools are allowed. + - `"logs"` - - `read_only: optional boolean` + - `CodeInterpreterImageOutput object { image, 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. + - `image: object { file_id }` - - `tool_names: optional array of string` + - `file_id: string` - List of allowed tool names. + The [file](/docs/api-reference/files) ID of the image. - - `never: optional object { read_only, tool_names }` + - `type: "image"` - A filter object to specify which tools are allowed. + Always `image`. - - `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. + - `type: "code_interpreter"` - - `tool_names: optional array of string` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - List of allowed tool names. + - `"code_interpreter"` - - `McpToolApprovalSetting = "always" or "never"` + - `FileSearchToolCall object { id, file_search, 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. + - `id: string` - - `"always"` + The ID of the tool call object. - - `"never"` + - `file_search: object { ranking_options, results }` - - `server_description: optional string` + For now, this is always going to be an empty object. - Optional description of the MCP server, used to provide more context. + - `ranking_options: optional object { ranker, score_threshold }` - - `server_url: optional string` + The ranking options for the file search. - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `ranker: "auto" or "default_2024_08_21"` - - `tunnel_id: optional string` + The ranker to use for the file search. If not specified will use the `auto` ranker. - 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. + - `"auto"` - - `CodeInterpreter object { container, type, allowed_callers }` + - `"default_2024_08_21"` - A tool that runs Python code to help generate a response to a prompt. + - `score_threshold: number` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - 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. + - `results: optional array of object { file_id, file_name, score, content }` - - `string` + The results of the file search. - The container ID. + - `file_id: string` - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + The ID of the file that result was found in. - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `file_name: string` - - `type: "auto"` + The name of the file that result was found in. - Always `auto`. + - `score: number` - - `"auto"` + The score of the result. All values must be a floating point number between 0 and 1. - - `file_ids: optional array of string` + - `content: optional array of object { text, type }` - An optional list of uploaded files to make available to your code. + The content of the result that was found. The content is only included if requested via the include query parameter. - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `text: optional string` - The memory limit for the code interpreter container. + The text content of the file. - - `"1g"` + - `type: optional "text"` - - `"4g"` + The type of the content. - - `"16g"` + - `"text"` - - `"64g"` + - `type: "file_search"` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + The type of tool call. This is always going to be `file_search` for this type of tool call. - Network access policy for the container. + - `"file_search"` - - `BetaContainerNetworkPolicyDisabled object { type }` + - `FunctionToolCall object { id, function, type }` - - `type: "disabled"` + - `id: string` - Disable outbound network access. Always `disabled`. + The ID of the tool call object. - - `"disabled"` + - `function: object { arguments, name, output }` - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + The definition of the function that was called. - - `allowed_domains: array of string` + - `arguments: string` - A list of allowed domains when type is `allowlist`. + The arguments passed to the function. - - `type: "allowlist"` + - `name: string` - Allow outbound network access only to specified domains. Always `allowlist`. + The name of the function. - - `"allowlist"` + - `output: string` - - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` + The output of the function. This will be `null` if the outputs have not been [submitted](/docs/api-reference/runs/submitToolOutputs) yet. - Optional domain-scoped secrets for allowlisted domains. + - `type: "function"` - - `domain: string` + The type of tool call. This is always going to be `function` for this type of tool call. - The domain associated with the secret. + - `"function"` - - `name: string` + - `type: "tool_calls"` - The name of the secret to inject for the domain. + Always `tool_calls`. - - `value: string` + - `"tool_calls"` - The secret value to inject for the domain. + - `thread_id: string` - - `type: "code_interpreter"` + The ID of the [thread](/docs/api-reference/threads) that was run. - The type of the code interpreter tool. Always `code_interpreter`. + - `type: "message_creation" or "tool_calls"` - - `"code_interpreter"` + The type of run step, which can be either `message_creation` or `tool_calls`. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"message_creation"` - The tool invocation context(s). + - `"tool_calls"` - - `"direct"` + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - - `"programmatic"` + Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. - - `ProgrammaticToolCalling object { type }` + - `completion_tokens: number` - - `type: "programmatic_tool_calling"` + Number of completion tokens used over the course of the run step. - The type of the tool. Always `programmatic_tool_calling`. + - `prompt_tokens: number` - - `"programmatic_tool_calling"` + Number of prompt tokens used over the course of the run step. - - `ImageGeneration object { type, action, background, 9 more }` + - `total_tokens: number` - A tool that generates images using the GPT image models. + Total number of tokens used (prompt + completion). - - `type: "image_generation"` +- `first_id: string` - The type of the image generation tool. Always `image_generation`. +- `has_more: boolean` - - `"image_generation"` +- `last_id: string` - - `action: optional "generate" or "edit" or "auto"` +- `object: string` - Whether to generate a new image or edit an existing image. Default: `auto`. +### Example - - `"generate"` +```http +curl https://api.openai.com/v1/threads/$THREAD_ID/runs/$RUN_ID/steps \ + -H 'OpenAI-Beta: assistants=v2' \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - - `"edit"` +#### Response - - `"auto"` +```json +{ + "data": [ + { + "id": "id", + "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 + } + } + ], + "first_id": "step_abc123", + "has_more": false, + "last_id": "step_abc456", + "object": "list" +} +``` - - `background: optional "transparent" or "opaque" or "auto"` +### Example - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. +```http +curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/steps \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" +``` - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. +#### Response - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. +```json +{ + "object": "list", + "data": [ + { + "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 + } + } + ], + "first_id": "step_abc123", + "last_id": "step_abc456", + "has_more": false +} +``` - - `"transparent"` +## Retrieve run step - - `"opaque"` +**get** `/threads/{thread_id}/runs/{run_id}/steps/{step_id}` - - `"auto"` +Retrieves a run step. - - `input_fidelity: optional "high" or "low"` +### Path Parameters - Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. +- `thread_id: string` - - `"high"` +- `run_id: string` - - `"low"` +- `step_id: string` - - `input_image_mask: optional object { file_id, image_url }` +### Query Parameters - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). +- `include: optional array of RunStepInclude` - - `file_id: 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. - File ID for the mask image. + See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `image_url: optional string` + - `"step_details.tool_calls[*].file_search.results[*].content"` - Base64-encoded mask image. +### Returns - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` +- `RunStep object { id, assistant_id, cancelled_at, 13 more }` - The image generation model to use. Default: `gpt-image-1`. + Represents a step in execution of a run. - - `string` + - `id: string` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + The identifier of the run step, which can be referenced in API endpoints. - The image generation model to use. Default: `gpt-image-1`. + - `assistant_id: string` - - `"gpt-image-1"` + The ID of the [assistant](/docs/api-reference/assistants) associated with the run step. - - `"gpt-image-1-mini"` + - `cancelled_at: number` - - `"gpt-image-2"` + The Unix timestamp (in seconds) for when the run step was cancelled. - - `"gpt-image-2-2026-04-21"` + - `completed_at: number` - - `"gpt-image-1.5"` + The Unix timestamp (in seconds) for when the run step completed. - - `"chatgpt-image-latest"` + - `created_at: number` - - `moderation: optional "auto" or "low"` + The Unix timestamp (in seconds) for when the run step was created. - Moderation level for the generated image. Default: `auto`. + - `expired_at: number` - - `"auto"` + The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. - - `"low"` + - `failed_at: number` - - `output_compression: optional number` + The Unix timestamp (in seconds) for when the run step failed. - Compression level for the output image. Default: 100. + - `last_error: object { code, message }` - - `output_format: optional "png" or "webp" or "jpeg"` + The last error associated with this run step. Will be `null` if there are no errors. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `code: "server_error" or "rate_limit_exceeded"` - - `"png"` + One of `server_error` or `rate_limit_exceeded`. - - `"webp"` + - `"server_error"` - - `"jpeg"` + - `"rate_limit_exceeded"` - - `partial_images: optional number` + - `message: string` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + A human-readable description of the error. - - `quality: optional "low" or "medium" or "high" or "auto"` + - `metadata: Metadata` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `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. - - `"medium"` + - `object: "thread.run.step"` - - `"high"` + The object type, which is always `thread.run.step`. - - `"auto"` + - `"thread.run.step"` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `run_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 [run](/docs/api-reference/runs) that this run step is a part of. - - `string` + - `status: "in_progress" or "cancelled" or "failed" or 2 more` - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. - 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"` - - `"1024x1024"` + - `"cancelled"` - - `"1024x1536"` + - `"failed"` - - `"1536x1024"` + - `"completed"` - - `"auto"` + - `"expired"` - - `LocalShell object { type }` + - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` - A tool that allows the model to execute shell commands in a local environment. + The details of the run step. - - `type: "local_shell"` + - `MessageCreationStepDetails object { message_creation, type }` - The type of the local shell tool. Always `local_shell`. + Details of the message creation by the run step. - - `"local_shell"` + - `message_creation: object { message_id }` - - `Shell object { type, allowed_callers, environment }` + - `message_id: string` - A tool that allows the model to execute shell commands. + The ID of the message that was created by this run step. - - `type: "shell"` + - `type: "message_creation"` - The type of the shell tool. Always `shell`. + Always `message_creation`. - - `"shell"` + - `"message_creation"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `ToolCallsStepDetails object { tool_calls, type }` - The tool invocation context(s). + Details of the tool call. - - `"direct"` + - `tool_calls: array of CodeInterpreterToolCall or FileSearchToolCall or FunctionToolCall` - - `"programmatic"` + 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`. - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + - `CodeInterpreterToolCall object { id, code_interpreter, type }` - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + Details of the Code Interpreter tool call the run step was involved in. - - `type: "container_auto"` + - `id: string` - Automatically creates a container for this request + The ID of the tool call. - - `"container_auto"` + - `code_interpreter: object { input, outputs }` - - `file_ids: optional array of string` + The Code Interpreter tool call definition. - An optional list of uploaded files to make available to your code. + - `input: string` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + The input to the Code Interpreter tool call. - The memory limit for the container. + - `outputs: array of object { logs, type } or object { image, type }` - - `"1g"` + 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. - - `"4g"` + - `CodeInterpreterLogOutput object { logs, type }` - - `"16g"` + Text output from the Code Interpreter tool call as part of a run step. - - `"64g"` + - `logs: string` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + The text output from the Code Interpreter tool call. - Network access policy for the container. + - `type: "logs"` - - `BetaContainerNetworkPolicyDisabled object { type }` + Always `logs`. - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `"logs"` - - `skills: optional array of BetaSkillReference or BetaInlineSkill` + - `CodeInterpreterImageOutput object { image, type }` - An optional list of skills referenced by id or inline data. + - `image: object { file_id }` - - `BetaSkillReference object { skill_id, type, version }` + - `file_id: string` - - `skill_id: string` + The [file](/docs/api-reference/files) ID of the image. - The ID of the referenced skill. + - `type: "image"` - - `type: "skill_reference"` + Always `image`. - References a skill created with the /v1/skills endpoint. + - `"image"` - - `"skill_reference"` + - `type: "code_interpreter"` - - `version: optional string` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `"code_interpreter"` - - `BetaInlineSkill object { description, name, source, type }` + - `FileSearchToolCall object { id, file_search, type }` - - `description: string` + - `id: string` - The description of the skill. + The ID of the tool call object. - - `name: string` + - `file_search: object { ranking_options, results }` - The name of the skill. + For now, this is always going to be an empty object. - - `source: BetaInlineSkillSource` + - `ranking_options: optional object { ranker, score_threshold }` - Inline skill payload + The ranking options for the file search. - - `data: string` + - `ranker: "auto" or "default_2024_08_21"` - Base64-encoded skill zip bundle. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `media_type: "application/zip"` + - `"auto"` - The media type of the inline skill payload. Must be `application/zip`. + - `"default_2024_08_21"` - - `"application/zip"` + - `score_threshold: number` - - `type: "base64"` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - The type of the inline skill source. Must be `base64`. + - `results: optional array of object { file_id, file_name, score, content }` - - `"base64"` + The results of the file search. - - `type: "inline"` + - `file_id: string` - Defines an inline skill for this request. + The ID of the file that result was found in. - - `"inline"` + - `file_name: string` - - `BetaLocalEnvironment object { type, skills }` + The name of the file that result was found in. - - `type: "local"` + - `score: number` - Use a local computer environment. + The score of the result. All values must be a floating point number between 0 and 1. - - `"local"` + - `content: optional array of object { text, type }` - - `skills: optional array of BetaLocalSkill` + The content of the result that was found. The content is only included if requested via the include query parameter. - An optional list of skills. + - `text: optional string` - - `description: string` + The text content of the file. - The description of the skill. + - `type: optional "text"` - - `name: string` + The type of the content. - The name of the skill. + - `"text"` - - `path: string` + - `type: "file_search"` - The path to the directory containing the skill. + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `BetaContainerReference object { container_id, type }` + - `"file_search"` - - `container_id: string` + - `FunctionToolCall object { id, function, type }` - The ID of the referenced container. + - `id: string` - - `type: "container_reference"` + The ID of the tool call object. - References a container created with the /v1/containers endpoint + - `function: object { arguments, name, output }` - - `"container_reference"` + The definition of the function that was called. - - `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](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The arguments passed to the function. - `name: string` - The name of the custom tool, used to identify it in tool calls. + The name of the function. - - `type: "custom"` + - `output: string` - The type of the custom tool. Always `custom`. + The output of the function. This will be `null` if the outputs have not been [submitted](/docs/api-reference/runs/submitToolOutputs) yet. - - `"custom"` + - `type: "function"` - - `allowed_callers: optional array of "direct" or "programmatic"` + The type of tool call. This is always going to be `function` for this type of tool call. - The tool invocation context(s). + - `"function"` - - `"direct"` + - `type: "tool_calls"` - - `"programmatic"` + Always `tool_calls`. - - `defer_loading: optional boolean` + - `"tool_calls"` - Whether this tool should be deferred and discovered via tool search. + - `thread_id: string` - - `description: optional string` + The ID of the [thread](/docs/api-reference/threads) that was run. - Optional description of the custom tool, used to provide more context. + - `type: "message_creation" or "tool_calls"` - - `format: optional object { type } or object { definition, syntax, type }` + The type of run step, which can be either `message_creation` or `tool_calls`. - The input format for the custom tool. Default is unconstrained text. + - `"message_creation"` - - `Text object { type }` + - `"tool_calls"` - Unconstrained free-form text. + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - - `type: "text"` + Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. - Unconstrained text format. Always `text`. + - `completion_tokens: number` - - `"text"` + Number of completion tokens used over the course of the run step. - - `Grammar object { definition, syntax, type }` + - `prompt_tokens: number` - A grammar defined by the user. + Number of prompt tokens used over the course of the run step. - - `definition: string` + - `total_tokens: number` - The grammar definition. + Total number of tokens used (prompt + completion). - - `syntax: "lark" or "regex"` +### Example - The syntax of the grammar definition. One of `lark` or `regex`. +```http +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" +``` - - `"lark"` +#### Response + +```json +{ + "id": "id", + "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 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" +``` - - `"regex"` +#### Response - - `type: "grammar"` +```json +{ + "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 + } +} +``` - Grammar format. Always `grammar`. +## Domain Types - - `"grammar"` +### Code Interpreter Logs - - `Namespace object { description, name, tools, type }` +- `CodeInterpreterLogs object { index, type, logs }` - Groups function/custom tools under a shared namespace. + Text output from the Code Interpreter tool call as part of a run step. - - `description: string` + - `index: number` - A description of the namespace shown to the model. + The index of the output in the outputs array. - - `name: string` + - `type: "logs"` - The namespace name used in tool calls (for example, `crm`). + Always `logs`. - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + - `"logs"` - The function/custom tools available inside this namespace. + - `logs: optional string` - - `Function object { name, type, allowed_callers, 5 more }` + The text output from the Code Interpreter tool call. - - `name: string` +### Code Interpreter Output Image - - `type: "function"` +- `CodeInterpreterOutputImage object { index, type, image }` - - `"function"` + - `index: number` - - `allowed_callers: optional array of "direct" or "programmatic"` + The index of the output in the outputs array. - The tool invocation context(s). + - `type: "image"` - - `"direct"` + Always `image`. - - `"programmatic"` + - `"image"` - - `defer_loading: optional boolean` + - `image: optional object { file_id }` - Whether this function should be deferred and discovered via tool search. + - `file_id: optional string` - - `description: optional string` + The [file](/docs/api-reference/files) ID of the image. - - `output_schema: optional map[unknown]` +### Code Interpreter Tool Call - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. +- `CodeInterpreterToolCall object { id, code_interpreter, type }` - - `parameters: optional unknown` + Details of the Code Interpreter tool call the run step was involved in. - - `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 ID of the tool call. - - `Custom object { name, type, allowed_callers, 3 more }` + - `code_interpreter: object { input, outputs }` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The Code Interpreter tool call definition. - - `name: string` + - `input: string` - The name of the custom tool, used to identify it in tool calls. + The input to the Code Interpreter tool call. - - `type: "custom"` + - `outputs: array of object { logs, type } or object { image, type }` - The type of the custom tool. Always `custom`. + 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. - - `"custom"` + - `CodeInterpreterLogOutput object { logs, type }` - - `allowed_callers: optional array of "direct" or "programmatic"` + Text output from the Code Interpreter tool call as part of a run step. - The tool invocation context(s). + - `logs: string` - - `"direct"` + The text output from the Code Interpreter tool call. - - `"programmatic"` + - `type: "logs"` - - `defer_loading: optional boolean` + Always `logs`. - Whether this tool should be deferred and discovered via tool search. + - `"logs"` - - `description: optional string` + - `CodeInterpreterImageOutput object { image, type }` - Optional description of the custom tool, used to provide more context. + - `image: object { file_id }` - - `format: optional object { type } or object { definition, syntax, type }` + - `file_id: string` - The input format for the custom tool. Default is unconstrained text. + The [file](/docs/api-reference/files) ID of the image. - - `Text object { type }` + - `type: "image"` - Unconstrained free-form text. + Always `image`. - - `type: "text"` + - `"image"` - Unconstrained text format. Always `text`. + - `type: "code_interpreter"` - - `"text"` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - `Grammar object { definition, syntax, type }` + - `"code_interpreter"` - A grammar defined by the user. +### Code Interpreter Tool Call Delta - - `definition: string` +- `CodeInterpreterToolCallDelta object { index, type, id, code_interpreter }` - The grammar definition. + Details of the Code Interpreter tool call the run step was involved in. - - `syntax: "lark" or "regex"` + - `index: number` - The syntax of the grammar definition. One of `lark` or `regex`. + The index of the tool call in the tool calls array. - - `"lark"` + - `type: "code_interpreter"` - - `"regex"` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - `type: "grammar"` + - `"code_interpreter"` - Grammar format. Always `grammar`. + - `id: optional string` - - `"grammar"` + The ID of the tool call. - - `type: "namespace"` + - `code_interpreter: optional object { input, outputs }` - The type of the tool. Always `namespace`. + The Code Interpreter tool call definition. - - `"namespace"` + - `input: optional string` - - `ToolSearch object { type, description, execution, parameters }` + The input to the Code Interpreter tool call. - Hosted or BYOT tool search configuration for deferred tools. + - `outputs: optional array of CodeInterpreterLogs or CodeInterpreterOutputImage` - - `type: "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. - The type of the tool. Always `tool_search`. + - `CodeInterpreterLogs object { index, type, logs }` - - `"tool_search"` + Text output from the Code Interpreter tool call as part of a run step. - - `description: optional string` + - `index: number` - Description shown to the model for a client-executed tool search tool. + The index of the output in the outputs array. - - `execution: optional "server" or "client"` + - `type: "logs"` - Whether tool search is executed by the server or by the client. + Always `logs`. - - `"server"` + - `"logs"` - - `"client"` + - `logs: optional string` - - `parameters: optional unknown` + The text output from the Code Interpreter tool call. - Parameter schema for a client-executed tool search tool. + - `CodeInterpreterOutputImage object { index, type, image }` - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + - `index: 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 index of the output in the outputs array. - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `type: "image"` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + Always `image`. - - `"web_search_preview"` + - `"image"` - - `"web_search_preview_2025_03_11"` + - `image: optional object { file_id }` - - `search_content_types: optional array of "text" or "image"` + - `file_id: optional string` - - `"text"` + The [file](/docs/api-reference/files) ID of the image. - - `"image"` +### File Search Tool Call - - `search_context_size: optional "low" or "medium" or "high"` +- `FileSearchToolCall object { id, file_search, 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. + - `id: string` - - `"low"` + The ID of the tool call object. - - `"medium"` + - `file_search: object { ranking_options, results }` - - `"high"` + For now, this is always going to be an empty object. - - `user_location: optional object { type, city, country, 2 more }` + - `ranking_options: optional object { ranker, score_threshold }` - The user's location. + The ranking options for the file search. - - `type: "approximate"` + - `ranker: "auto" or "default_2024_08_21"` - The type of location approximation. Always `approximate`. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `"approximate"` + - `"auto"` - - `city: optional string` + - `"default_2024_08_21"` - Free text input for the city of the user, e.g. `San Francisco`. + - `score_threshold: number` - - `country: optional string` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `results: optional array of object { file_id, file_name, score, content }` - - `region: optional string` + The results of the file search. - Free text input for the region of the user, e.g. `California`. + - `file_id: string` - - `timezone: optional string` + The ID of the file that result was found in. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `file_name: string` - - `ApplyPatch object { type, allowed_callers }` + The name of the file that result was found in. - Allows the assistant to create, delete, or update files using unified diffs. + - `score: number` - - `type: "apply_patch"` + The score of the result. All values must be a floating point number between 0 and 1. - The type of the tool. Always `apply_patch`. + - `content: optional array of object { text, type }` - - `"apply_patch"` + The content of the result that was found. The content is only included if requested via the include query parameter. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `text: optional string` - The tool invocation context(s). + The text content of the file. - - `"direct"` + - `type: optional "text"` - - `"programmatic"` + The type of the content. - - `type: "tool_search_output"` + - `"text"` - The item type. Always `tool_search_output`. + - `type: "file_search"` - - `"tool_search_output"` + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `id: optional string` + - `"file_search"` - The unique ID of this tool search output. +### File Search Tool Call Delta - - `agent: optional object { agent_name }` +- `FileSearchToolCallDelta object { file_search, index, type, id }` - The agent that produced this item. + - `file_search: unknown` - - `agent_name: string` + For now, this is always going to be an empty object. - The canonical name of the agent that produced this item. + - `index: number` - - `call_id: optional string` + The index of the tool call in the tool calls array. - The unique ID of the tool search call generated by the model. + - `type: "file_search"` - - `execution: optional "server" or "client"` + The type of tool call. This is always going to be `file_search` for this type of tool call. - Whether tool search was executed by the server or by the client. + - `"file_search"` - - `"server"` + - `id: optional string` - - `"client"` + The ID of the tool call object. - - `status: optional "in_progress" or "completed" or "incomplete"` +### Function Tool Call - The status of the tool search output. +- `FunctionToolCall object { id, function, type }` - - `"in_progress"` + - `id: string` - - `"completed"` + The ID of the tool call object. - - `"incomplete"` + - `function: object { arguments, name, output }` - - `AdditionalTools object { role, tools, type, 2 more }` + The definition of the function that was called. - - `role: "developer"` + - `arguments: string` - The role that provided the additional tools. Only `developer` is supported. + The arguments passed to the function. - - `"developer"` + - `name: 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 name of the function. - A list of additional tools made available at this item. + - `output: string` - - `Function object { name, parameters, strict, 5 more }` + The output of the function. This will be `null` if the outputs have not been [submitted](/docs/api-reference/runs/submitToolOutputs) yet. - 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: "function"` - - `name: string` + The type of tool call. This is always going to be `function` for this type of tool call. - The name of the function to call. + - `"function"` - - `parameters: map[unknown]` +### Function Tool Call Delta - A JSON schema object describing the parameters of the function. +- `FunctionToolCallDelta object { index, type, id, function }` - - `strict: boolean` + - `index: number` - Whether strict parameter validation is enforced for this function tool. + The index of the tool call in the tool calls array. - `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"` - - The tool invocation context(s). + - `id: optional string` - - `"direct"` + The ID of the tool call object. - - `"programmatic"` + - `function: optional object { arguments, name, output }` - - `defer_loading: optional boolean` + The definition of the function that was called. - Whether this function is deferred and loaded via tool search. + - `arguments: optional string` - - `description: optional string` + The arguments passed to the function. - A description of the function. Used by the model to determine whether or not to call the function. + - `name: optional string` - - `output_schema: optional map[unknown]` + The name of the function. - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `output: optional string` - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + The output of the function. This will be `null` if the outputs have not been [submitted](/docs/api-reference/runs/submitToolOutputs) yet. - 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 Creation Step Details - - `type: "file_search"` +- `MessageCreationStepDetails object { message_creation, type }` - The type of the file search tool. Always `file_search`. + Details of the message creation by the run step. - - `"file_search"` + - `message_creation: object { message_id }` - - `vector_store_ids: array of string` + - `message_id: string` - The IDs of the vector stores to search. + The ID of the message that was created by this run step. - - `filters: optional object { key, type, value } or object { filters, type }` + - `type: "message_creation"` - A filter to apply. + Always `message_creation`. - - `ComparisonFilter object { key, type, value }` + - `"message_creation"` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. +### Run Step - - `key: string` +- `RunStep object { id, assistant_id, cancelled_at, 13 more }` - The key to compare against the value. + Represents a step in execution of a run. - - `type: "eq" or "ne" or "gt" or 5 more` + - `id: string` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The identifier of the run step, which can be referenced in API endpoints. - - `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 + - `assistant_id: string` - - `"eq"` + The ID of the [assistant](/docs/api-reference/assistants) associated with the run step. - - `"ne"` + - `cancelled_at: number` - - `"gt"` + The Unix timestamp (in seconds) for when the run step was cancelled. - - `"gte"` + - `completed_at: number` - - `"lt"` + The Unix timestamp (in seconds) for when the run step completed. - - `"lte"` + - `created_at: number` - - `"in"` + The Unix timestamp (in seconds) for when the run step was created. - - `"nin"` + - `expired_at: number` - - `value: string or number or boolean or array of string or number` + The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. - The value to compare against the attribute key; supports string, number, or boolean types. + - `failed_at: number` - - `string` + The Unix timestamp (in seconds) for when the run step failed. - - `number` + - `last_error: object { code, message }` - - `boolean` + The last error associated with this run step. Will be `null` if there are no errors. - - `array of string or number` + - `code: "server_error" or "rate_limit_exceeded"` - - `string` + One of `server_error` or `rate_limit_exceeded`. - - `number` + - `"server_error"` - - `CompoundFilter object { filters, type }` + - `"rate_limit_exceeded"` - Combine multiple filters using `and` or `or`. + - `message: string` - - `filters: array of object { key, type, value } or unknown` + A human-readable description of the error. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `metadata: Metadata` - - `ComparisonFilter object { key, type, 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. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `key: string` + - `object: "thread.run.step"` - The key to compare against the value. + The object type, which is always `thread.run.step`. - - `type: "eq" or "ne" or "gt" or 5 more` + - `"thread.run.step"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `run_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 [run](/docs/api-reference/runs) that this run step is a part of. - - `"eq"` + - `status: "in_progress" or "cancelled" or "failed" or 2 more` - - `"ne"` + The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. - - `"gt"` + - `"in_progress"` - - `"gte"` + - `"cancelled"` - - `"lt"` + - `"failed"` - - `"lte"` + - `"completed"` - - `"in"` + - `"expired"` - - `"nin"` + - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` - - `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. + - `MessageCreationStepDetails object { message_creation, type }` - - `string` + Details of the message creation by the run step. - - `number` + - `message_creation: object { message_id }` - - `boolean` + - `message_id: string` - - `array of string or number` + The ID of the message that was created by this run step. - - `string` + - `type: "message_creation"` - - `number` + Always `message_creation`. - - `unknown` + - `"message_creation"` - - `type: "and" or "or"` + - `ToolCallsStepDetails object { tool_calls, type }` - Type of operation: `and` or `or`. + Details of the tool call. - - `"and"` + - `tool_calls: array of CodeInterpreterToolCall or FileSearchToolCall or FunctionToolCall` - - `"or"` + 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`. - - `max_num_results: optional number` + - `CodeInterpreterToolCall object { id, code_interpreter, type }` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + Details of the Code Interpreter tool call the run step was involved in. - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `id: string` - Ranking options for search. + The ID of the tool call. - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `code_interpreter: object { input, outputs }` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + The Code Interpreter tool call definition. - - `embedding_weight: number` + - `input: string` - The weight of the embedding in the reciprocal ranking fusion. + The input to the Code Interpreter tool call. - - `text_weight: number` + - `outputs: array of object { logs, type } or object { image, type }` - The weight of the text in the reciprocal ranking fusion. + 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. - - `ranker: optional "auto" or "default-2024-11-15"` + - `CodeInterpreterLogOutput object { logs, type }` - The ranker to use for the file search. + Text output from the Code Interpreter tool call as part of a run step. - - `"auto"` + - `logs: string` - - `"default-2024-11-15"` + The text output from the Code Interpreter tool call. - - `score_threshold: optional number` + - `type: "logs"` - 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. + Always `logs`. - - `Computer object { type }` + - `"logs"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `CodeInterpreterImageOutput object { image, type }` - - `type: "computer"` + - `image: object { file_id }` - The type of the computer tool. Always `computer`. + - `file_id: string` - - `"computer"` + The [file](/docs/api-reference/files) ID of the image. - - `ComputerUsePreview object { display_height, display_width, environment, type }` + - `type: "image"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + Always `image`. - - `display_height: number` + - `"image"` - The height of the computer display. + - `type: "code_interpreter"` - - `display_width: number` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - The width of the computer display. + - `"code_interpreter"` - - `environment: "windows" or "mac" or "linux" or 2 more` + - `FileSearchToolCall object { id, file_search, type }` - The type of computer environment to control. + - `id: string` - - `"windows"` + The ID of the tool call object. - - `"mac"` + - `file_search: object { ranking_options, results }` - - `"linux"` + For now, this is always going to be an empty object. - - `"ubuntu"` + - `ranking_options: optional object { ranker, score_threshold }` - - `"browser"` + The ranking options for the file search. - - `type: "computer_use_preview"` + - `ranker: "auto" or "default_2024_08_21"` - The type of the computer use tool. Always `computer_use_preview`. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `"computer_use_preview"` + - `"auto"` - - `WebSearch object { type, filters, search_context_size, user_location }` + - `"default_2024_08_21"` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `score_threshold: number` - - `type: "web_search" or "web_search_2025_08_26"` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `results: optional array of object { file_id, file_name, score, content }` - - `"web_search"` + The results of the file search. - - `"web_search_2025_08_26"` + - `file_id: string` - - `filters: optional object { allowed_domains }` + The ID of the file that result was found in. - Filters for the search. + - `file_name: string` - - `allowed_domains: optional array of string` + The name of the file that result was found in. - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `score: number` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + The score of the result. All values must be a floating point number between 0 and 1. - - `search_context_size: optional "low" or "medium" or "high"` + - `content: optional array of object { text, 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 content of the result that was found. The content is only included if requested via the include query parameter. - - `"low"` + - `text: optional string` - - `"medium"` + The text content of the file. - - `"high"` + - `type: optional "text"` - - `user_location: optional object { city, country, region, 2 more }` + The type of the content. - The approximate location of the user. + - `"text"` - - `city: optional string` + - `type: "file_search"` - Free text input for the city of the user, e.g. `San Francisco`. + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `country: optional string` + - `"file_search"` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `FunctionToolCall object { id, function, type }` - - `region: optional string` + - `id: string` - Free text input for the region of the user, e.g. `California`. + The ID of the tool call object. - - `timezone: optional string` + - `function: object { arguments, name, output }` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The definition of the function that was called. - - `type: optional "approximate"` + - `arguments: string` - The type of location approximation. Always `approximate`. + The arguments passed to the function. - - `"approximate"` + - `name: string` - - `Mcp object { server_label, type, allowed_callers, 9 more }` + The name of the function. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `output: string` - - `server_label: string` + The output of the function. This will be `null` if the outputs have not been [submitted](/docs/api-reference/runs/submitToolOutputs) yet. - A label for this MCP server, used to identify it in tool calls. + - `type: "function"` - - `type: "mcp"` + The type of tool call. This is always going to be `function` for this type of tool call. - The type of the MCP tool. Always `mcp`. + - `"function"` - - `"mcp"` + - `type: "tool_calls"` - - `allowed_callers: optional array of "direct" or "programmatic"` + Always `tool_calls`. - The tool invocation context(s). + - `"tool_calls"` - - `"direct"` + - `thread_id: string` - - `"programmatic"` + The ID of the [thread](/docs/api-reference/threads) that was run. - - `allowed_tools: optional array of string or object { read_only, tool_names }` + - `type: "message_creation" or "tool_calls"` - List of allowed tool names or a filter object. + The type of run step, which can be either `message_creation` or `tool_calls`. - - `McpAllowedTools = array of string` + - `"message_creation"` - A string array of allowed tool names + - `"tool_calls"` - - `McpToolFilter object { read_only, tool_names }` + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - A filter object to specify which tools are allowed. + Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. - - `read_only: optional boolean` + - `completion_tokens: 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. + Number of completion tokens used over the course of the run step. - - `tool_names: optional array of string` + - `prompt_tokens: number` - List of allowed tool names. + Number of prompt tokens used over the course of the run step. - - `authorization: optional string` + - `total_tokens: 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. + Total number of tokens used (prompt + completion). - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` +### Run Step Delta Event - 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). +- `RunStepDeltaEvent object { id, delta, object }` - Currently supported `connector_id` values are: + Represents a run step delta i.e. any changed fields on a run step during streaming. - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + - `id: string` - - `"connector_dropbox"` + The identifier of the run step, which can be referenced in API endpoints. - - `"connector_gmail"` + - `delta: object { step_details }` - - `"connector_googlecalendar"` + The delta containing the fields that have changed on the run step. - - `"connector_googledrive"` + - `step_details: optional RunStepDeltaMessageDelta or ToolCallDeltaObject` - - `"connector_microsoftteams"` + The details of the run step. - - `"connector_outlookcalendar"` + - `RunStepDeltaMessageDelta object { type, message_creation }` - - `"connector_outlookemail"` + Details of the message creation by the run step. - - `"connector_sharepoint"` + - `type: "message_creation"` - - `defer_loading: optional boolean` + Always `message_creation`. - Whether this MCP tool is deferred and discovered via tool search. + - `"message_creation"` - - `headers: optional map[string]` + - `message_creation: optional object { message_id }` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `message_id: optional string` - - `require_approval: optional object { always, never } or "always" or "never"` + The ID of the message that was created by this run step. - Specify which of the MCP server's tools require approval. + - `ToolCallDeltaObject object { type, tool_calls }` - - `McpToolApprovalFilter object { always, never }` + Details of the 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. + - `type: "tool_calls"` - - `always: optional object { read_only, tool_names }` + Always `tool_calls`. - A filter object to specify which tools are allowed. + - `"tool_calls"` - - `read_only: optional boolean` + - `tool_calls: optional array of CodeInterpreterToolCallDelta or FileSearchToolCallDelta or FunctionToolCallDelta` - 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. + 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`. - - `tool_names: optional array of string` + - `CodeInterpreterToolCallDelta object { index, type, id, code_interpreter }` - List of allowed tool names. + Details of the Code Interpreter tool call the run step was involved in. - - `never: optional object { read_only, tool_names }` + - `index: number` - A filter object to specify which tools are allowed. + The index of the tool call in the tool calls array. - - `read_only: optional boolean` + - `type: "code_interpreter"` - 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 tool call. This is always going to be `code_interpreter` for this type of tool call. - - `tool_names: optional array of string` + - `"code_interpreter"` - List of allowed tool names. + - `id: optional string` - - `McpToolApprovalSetting = "always" or "never"` + The 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. + - `code_interpreter: optional object { input, outputs }` - - `"always"` + The Code Interpreter tool call definition. - - `"never"` + - `input: optional string` - - `server_description: optional string` + The input to the Code Interpreter tool call. - Optional description of the MCP server, used to provide more context. + - `outputs: optional array of CodeInterpreterLogs or CodeInterpreterOutputImage` - - `server_url: 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 URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `CodeInterpreterLogs object { index, type, logs }` - - `tunnel_id: optional string` + Text output from the Code Interpreter tool call as part of a run step. - 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. + - `index: number` - - `CodeInterpreter object { container, type, allowed_callers }` + The index of the output in the outputs array. - A tool that runs Python code to help generate a response to a prompt. + - `type: "logs"` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + Always `logs`. - 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. + - `"logs"` - - `string` + - `logs: optional string` - The container ID. + The text output from the Code Interpreter tool call. - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + - `CodeInterpreterOutputImage object { index, type, image }` - 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 output in the outputs array. - Always `auto`. + - `type: "image"` - - `"auto"` + Always `image`. - - `file_ids: optional array of string` + - `"image"` - An optional list of uploaded files to make available to your code. + - `image: optional object { file_id }` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `file_id: optional string` - The memory limit for the code interpreter container. + The [file](/docs/api-reference/files) ID of the image. - - `"1g"` + - `FileSearchToolCallDelta object { file_search, index, type, id }` - - `"4g"` + - `file_search: unknown` - - `"16g"` + For now, this is always going to be an empty object. - - `"64g"` + - `index: number` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + The index of the tool call in the tool calls array. - Network access policy for the container. + - `type: "file_search"` - - `BetaContainerNetworkPolicyDisabled object { type }` + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `"file_search"` - - `type: "code_interpreter"` + - `id: optional string` - The type of the code interpreter tool. Always `code_interpreter`. + The ID of the tool call object. - - `"code_interpreter"` + - `FunctionToolCallDelta object { index, type, id, function }` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `index: number` - The tool invocation context(s). + The index of the tool call in the tool calls array. - - `"direct"` + - `type: "function"` - - `"programmatic"` + The type of tool call. This is always going to be `function` for this type of tool call. - - `ProgrammaticToolCalling object { type }` + - `"function"` - - `type: "programmatic_tool_calling"` + - `id: optional string` - The type of the tool. Always `programmatic_tool_calling`. + The ID of the tool call object. - - `"programmatic_tool_calling"` + - `function: optional object { arguments, name, output }` - - `ImageGeneration object { type, action, background, 9 more }` + The definition of the function that was called. - A tool that generates images using the GPT image models. + - `arguments: optional string` - - `type: "image_generation"` + The arguments passed to the function. - The type of the image generation tool. Always `image_generation`. + - `name: optional string` - - `"image_generation"` + The name of the function. - - `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 of the function. This will be `null` if the outputs have not been [submitted](/docs/api-reference/runs/submitToolOutputs) yet. - - `"generate"` + - `object: "thread.run.step.delta"` - - `"edit"` + The object type, which is always `thread.run.step.delta`. - - `"auto"` + - `"thread.run.step.delta"` - - `background: optional "transparent" or "opaque" or "auto"` +### Run Step Delta Message Delta - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. +- `RunStepDeltaMessageDelta object { type, message_creation }` - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + Details of the message creation by the run step. - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `type: "message_creation"` - - `"transparent"` + Always `message_creation`. - - `"opaque"` + - `"message_creation"` - - `"auto"` + - `message_creation: optional object { message_id }` - - `input_fidelity: optional "high" or "low"` + - `message_id: 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 message that was created by this run step. - - `"high"` +### Run Step Include - - `"low"` +- `RunStepInclude = "step_details.tool_calls[*].file_search.results[*].content"` - - `input_image_mask: optional object { file_id, image_url }` + - `"step_details.tool_calls[*].file_search.results[*].content"` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). +### Tool Call Delta Object - - `file_id: optional string` +- `ToolCallDeltaObject object { type, tool_calls }` - File ID for the mask image. + Details of the tool call. - - `image_url: optional string` + - `type: "tool_calls"` - Base64-encoded mask image. + Always `tool_calls`. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `"tool_calls"` - The image generation model to use. Default: `gpt-image-1`. + - `tool_calls: optional array of CodeInterpreterToolCallDelta or FileSearchToolCallDelta or FunctionToolCallDelta` - - `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`. - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `CodeInterpreterToolCallDelta object { index, type, id, code_interpreter }` - The image generation model to use. Default: `gpt-image-1`. + Details of the Code Interpreter tool call the run step was involved in. - - `"gpt-image-1"` + - `index: number` - - `"gpt-image-1-mini"` + The index of the tool call in the tool calls array. - - `"gpt-image-2"` + - `type: "code_interpreter"` - - `"gpt-image-2-2026-04-21"` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - `"gpt-image-1.5"` + - `"code_interpreter"` - - `"chatgpt-image-latest"` + - `id: optional string` - - `moderation: optional "auto" or "low"` + The ID of the tool call. - Moderation level for the generated image. Default: `auto`. + - `code_interpreter: optional object { input, outputs }` - - `"auto"` + The Code Interpreter tool call definition. - - `"low"` + - `input: optional string` - - `output_compression: optional number` + The input to the Code Interpreter tool call. - Compression level for the output image. Default: 100. + - `outputs: optional array of CodeInterpreterLogs or CodeInterpreterOutputImage` - - `output_format: optional "png" or "webp" or "jpeg"` + 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 output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `CodeInterpreterLogs object { index, type, logs }` - - `"png"` + Text output from the Code Interpreter tool call as part of a run step. - - `"webp"` + - `index: number` - - `"jpeg"` + The index of the output in the outputs array. - - `partial_images: optional number` + - `type: "logs"` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + Always `logs`. - - `quality: optional "low" or "medium" or "high" or "auto"` + - `"logs"` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `logs: optional string` - - `"low"` + The text output from the Code Interpreter tool call. - - `"medium"` + - `CodeInterpreterOutputImage object { index, type, image }` - - `"high"` + - `index: number` - - `"auto"` + The index of the output in the outputs array. - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `type: "image"` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + Always `image`. - - `string` + - `"image"` - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `image: optional object { file_id }` - 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` - - `"1024x1024"` + The [file](/docs/api-reference/files) ID of the image. - - `"1024x1536"` + - `FileSearchToolCallDelta object { file_search, index, type, id }` - - `"1536x1024"` + - `file_search: unknown` - - `"auto"` + For now, this is always going to be an empty object. - - `LocalShell object { type }` + - `index: number` - A tool that allows the model to execute shell commands in a local environment. + The index of the tool call in the tool calls array. - - `type: "local_shell"` + - `type: "file_search"` - The type of the local shell tool. Always `local_shell`. + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `"local_shell"` + - `"file_search"` - - `Shell object { type, allowed_callers, environment }` + - `id: optional string` - A tool that allows the model to execute shell commands. + The ID of the tool call object. - - `type: "shell"` + - `FunctionToolCallDelta object { index, type, id, function }` - The type of the shell tool. Always `shell`. + - `index: number` - - `"shell"` + The index of the tool call in the tool calls array. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `type: "function"` - The tool invocation context(s). + The type of tool call. This is always going to be `function` for this type of tool call. - - `"direct"` + - `"function"` - - `"programmatic"` + - `id: optional string` - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + The ID of the tool call object. - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `function: optional object { arguments, name, output }` - - `BetaLocalEnvironment object { type, skills }` + The definition of the function that was called. - - `BetaContainerReference object { container_id, type }` + - `arguments: optional string` - - `Custom object { name, type, allowed_callers, 3 more }` + The arguments passed to the function. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `name: optional string` - - `name: string` + The name of the function. - The name of the custom tool, used to identify it in tool calls. + - `output: optional string` - - `type: "custom"` + 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 custom tool. Always `custom`. +### Tool Calls Step Details - - `"custom"` +- `ToolCallsStepDetails object { tool_calls, type }` - - `allowed_callers: optional array of "direct" or "programmatic"` + Details of the tool call. - The tool invocation context(s). + - `tool_calls: array of CodeInterpreterToolCall or FileSearchToolCall or FunctionToolCall` - - `"direct"` + 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`. - - `"programmatic"` + - `CodeInterpreterToolCall object { id, code_interpreter, type }` - - `defer_loading: optional boolean` + Details of the Code Interpreter tool call the run step was involved in. - Whether this tool should be deferred and discovered via tool search. + - `id: string` - - `description: optional string` + The ID of the tool call. - Optional description of the custom tool, used to provide more context. + - `code_interpreter: object { input, outputs }` - - `format: optional object { type } or object { definition, syntax, type }` + The Code Interpreter tool call definition. - The input format for the custom tool. Default is unconstrained text. + - `input: string` - - `Text object { type }` + The input to the Code Interpreter tool call. - Unconstrained free-form text. + - `outputs: array of object { logs, type } or object { image, type }` - - `type: "text"` + 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. - Unconstrained text format. Always `text`. + - `CodeInterpreterLogOutput object { logs, type }` - - `"text"` + Text output from the Code Interpreter tool call as part of a run step. - - `Grammar object { definition, syntax, type }` + - `logs: string` - A grammar defined by the user. + The text output from the Code Interpreter tool call. - - `definition: string` + - `type: "logs"` - The grammar definition. + Always `logs`. - - `syntax: "lark" or "regex"` + - `"logs"` - The syntax of the grammar definition. One of `lark` or `regex`. + - `CodeInterpreterImageOutput object { image, type }` - - `"lark"` + - `image: object { file_id }` - - `"regex"` + - `file_id: string` - - `type: "grammar"` + The [file](/docs/api-reference/files) ID of the image. - Grammar format. Always `grammar`. + - `type: "image"` - - `"grammar"` + Always `image`. - - `Namespace object { description, name, tools, type }` + - `"image"` - Groups function/custom tools under a shared namespace. + - `type: "code_interpreter"` - - `description: string` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - A description of the namespace shown to the model. + - `"code_interpreter"` - - `name: string` + - `FileSearchToolCall object { id, file_search, type }` - 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 ID of the tool call object. - The function/custom tools available inside this namespace. + - `file_search: object { ranking_options, results }` - - `Function object { name, type, allowed_callers, 5 more }` + For now, this is always going to be an empty object. - - `name: string` + - `ranking_options: optional object { ranker, score_threshold }` - - `type: "function"` + The ranking options for the file search. - - `"function"` + - `ranker: "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"` + - `score_threshold: number` - - `defer_loading: optional boolean` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - Whether this function should be deferred and discovered via tool search. + - `results: optional array of object { file_id, file_name, score, content }` - - `description: optional string` + The results of the file search. - - `output_schema: optional map[unknown]` + - `file_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 file that result was found in. - - `parameters: optional unknown` + - `file_name: string` - - `strict: optional boolean` + The name of the file that result was found in. - 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. + - `score: number` - - `Custom object { name, type, allowed_callers, 3 more }` + The score of the result. All values must be a floating point number between 0 and 1. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `content: optional array of object { text, type }` - - `name: string` + The content of the result that was found. The content is only included if requested via the include query parameter. - The name of the custom tool, used to identify it in tool calls. + - `text: optional string` - - `type: "custom"` + The text content of the file. - The type of the custom tool. Always `custom`. + - `type: optional "text"` - - `"custom"` + The type of the content. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"text"` - The tool invocation context(s). + - `type: "file_search"` - - `"direct"` + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `"programmatic"` + - `"file_search"` - - `defer_loading: optional boolean` + - `FunctionToolCall object { id, function, type }` - Whether this tool should be deferred and discovered via tool search. + - `id: string` - - `description: optional string` + The ID of the tool call object. - Optional description of the custom tool, used to provide more context. + - `function: object { arguments, name, output }` - - `format: optional object { type } or object { definition, syntax, type }` + The definition of the function that was called. - The input format for the custom tool. Default is unconstrained text. + - `arguments: string` - - `Text object { type }` + The arguments passed to the function. - Unconstrained free-form text. + - `name: string` - - `type: "text"` + The name of the function. - Unconstrained text format. Always `text`. + - `output: string` - - `"text"` + The output of the function. This will be `null` if the outputs have not been [submitted](/docs/api-reference/runs/submitToolOutputs) yet. - - `Grammar object { definition, syntax, type }` + - `type: "function"` - A grammar defined by the user. + The type of tool call. This is always going to be `function` for this type of tool call. - - `definition: string` + - `"function"` - The grammar definition. + - `type: "tool_calls"` - - `syntax: "lark" or "regex"` + Always `tool_calls`. - The syntax of the grammar definition. One of `lark` or `regex`. + - `"tool_calls"` - - `"lark"` +# Messages - - `"regex"` +## List messages - - `type: "grammar"` +**get** `/threads/{thread_id}/messages` - Grammar format. Always `grammar`. +Returns a list of messages for a given thread. - - `"grammar"` +### Path Parameters - - `type: "namespace"` +- `thread_id: string` - The type of the tool. Always `namespace`. +### Query Parameters - - `"namespace"` +- `after: optional string` - - `ToolSearch object { type, description, execution, 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. - Hosted or BYOT tool search configuration for deferred tools. +- `before: optional string` - - `type: "tool_search"` + 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 tool. Always `tool_search`. +- `limit: optional number` - - `"tool_search"` + A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. - - `description: optional string` +- `order: optional "asc" or "desc"` - Description shown to the model for a client-executed tool search tool. + Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. - - `execution: optional "server" or "client"` + - `"asc"` - Whether tool search is executed by the server or by the client. + - `"desc"` - - `"server"` +- `run_id: optional string` - - `"client"` + Filter messages by the run ID that generated them. - - `parameters: optional unknown` +### Returns - Parameter schema for a client-executed tool search tool. +- `data: array of Message` - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + - `id: string` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The identifier, which can be referenced in API endpoints. - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `assistant_id: string` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + If applicable, the ID of the [assistant](/docs/api-reference/assistants) that authored this message. - - `"web_search_preview"` + - `attachments: array of object { file_id, tools }` - - `"web_search_preview_2025_03_11"` + A list of files attached to the message, and the tools they were added to. - - `search_content_types: optional array of "text" or "image"` + - `file_id: optional string` - - `"text"` + The ID of the file to attach to the message. - - `"image"` + - `tools: optional array of CodeInterpreterTool or object { type }` - - `search_context_size: optional "low" or "medium" or "high"` + The tools to add this file 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. + - `CodeInterpreterTool object { type }` - - `"low"` + - `type: "code_interpreter"` - - `"medium"` + The type of tool being defined: `code_interpreter` - - `"high"` + - `"code_interpreter"` - - `user_location: optional object { type, city, country, 2 more }` + - `FileSearchTool object { type }` - The user's location. + - `type: "file_search"` - - `type: "approximate"` + The type of tool being defined: `file_search` - The type of location approximation. Always `approximate`. + - `"file_search"` - - `"approximate"` + - `completed_at: number` - - `city: optional string` + The Unix timestamp (in seconds) for when the message was completed. - Free text input for the city of the user, e.g. `San Francisco`. + - `content: array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlock or RefusalContentBlock` - - `country: optional string` + The content of the message in array of text and/or images. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `ImageFileContentBlock object { image_file, type }` - - `region: optional string` + References an image [File](/docs/api-reference/files) in the content of a message. - Free text input for the region of the user, e.g. `California`. + - `image_file: ImageFile` - - `timezone: optional string` + - `file_id: string` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + 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. - - `ApplyPatch object { type, allowed_callers }` + - `detail: optional "auto" or "low" or "high"` - Allows the assistant to create, delete, or update files using unified diffs. + 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: "apply_patch"` + - `"auto"` - The type of the tool. Always `apply_patch`. + - `"low"` - - `"apply_patch"` + - `"high"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `type: "image_file"` - The tool invocation context(s). + Always `image_file`. - - `"direct"` + - `"image_file"` - - `"programmatic"` + - `ImageURLContentBlock object { image_url, type }` - - `type: "additional_tools"` + References an image URL in the content of a message. - The item type. Always `additional_tools`. + - `image_url: ImageURL` - - `"additional_tools"` + - `url: string` - - `id: optional string` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - The unique ID of this additional tools item. + - `detail: optional "auto" or "low" or "high"` - - `agent: optional object { agent_name }` + 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 agent that produced this item. + - `"auto"` - - `agent_name: string` + - `"low"` - The canonical name of the agent that produced this item. + - `"high"` - - `Reasoning object { id, summary, type, 4 more }` + - `type: "image_url"` - 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](https://platform.openai.com/docs/guides/conversation-state). + The type of the content part. - - `id: string` + - `"image_url"` - The unique identifier of the reasoning content. + - `TextContentBlock object { text, type }` - - `summary: array of object { text, type }` + The text content that is part of a message. - Reasoning summary content. + - `text: Text` - - `text: string` + - `annotations: array of FileCitationAnnotation or FilePathAnnotation` - A summary of the reasoning output from the model so far. + - `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` - - `type: "summary_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 object. Always `summary_text`. + - `end_index: number` - - `"summary_text"` + - `file_citation: object { file_id }` - - `type: "reasoning"` + - `file_id: string` - The type of the object. Always `reasoning`. + The ID of the specific File the citation is from. - - `"reasoning"` + - `start_index: number` - - `agent: optional object { agent_name }` + - `text: string` - The agent that produced this item. + The text in the message content that needs to be replaced. - - `agent_name: string` + - `type: "file_citation"` - The canonical name of the agent that produced this item. + Always `file_citation`. - - `content: optional array of object { text, type }` + - `"file_citation"` - Reasoning text content. + - `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` - - `text: string` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - The reasoning text from the model. + - `end_index: number` - - `type: "reasoning_text"` + - `file_path: object { file_id }` - The type of the reasoning text. Always `reasoning_text`. + - `file_id: string` - - `"reasoning_text"` + The ID of the file that was generated. - - `encrypted_content: optional string` + - `start_index: number` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `text: string` - - `status: optional "in_progress" or "completed" or "incomplete"` + The text in the message content that needs to be replaced. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `type: "file_path"` - - `"in_progress"` + Always `file_path`. - - `"completed"` + - `"file_path"` - - `"incomplete"` + - `value: string` - - `Compaction object { encrypted_content, type, id, agent }` + The data that makes up the text. - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `type: "text"` - - `encrypted_content: string` + Always `text`. - The encrypted content of the compaction summary. + - `"text"` - - `type: "compaction"` + - `RefusalContentBlock object { refusal, type }` - The type of the item. Always `compaction`. + The refusal content generated by the assistant. - - `"compaction"` + - `refusal: string` - - `id: optional string` + - `type: "refusal"` - The ID of the compaction item. + Always `refusal`. - - `agent: optional object { agent_name }` + - `"refusal"` - The agent that produced this item. + - `created_at: number` - - `agent_name: string` + The Unix timestamp (in seconds) for when the message was created. - The canonical name of the agent that produced this item. + - `incomplete_at: number` - - `ImageGenerationCall object { id, result, status, 2 more }` + The Unix timestamp (in seconds) for when the message was marked as incomplete. - An image generation request made by the model. + - `incomplete_details: object { reason }` - - `id: string` + On an incomplete message, details about why the message is incomplete. - The unique ID of the image generation call. + - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` - - `result: string` + The reason the message is incomplete. - The generated image encoded in base64. + - `"content_filter"` - - `status: "in_progress" or "completed" or "generating" or "failed"` + - `"max_tokens"` - The status of the image generation call. + - `"run_cancelled"` - - `"in_progress"` + - `"run_expired"` - - `"completed"` + - `"run_failed"` - - `"generating"` + - `metadata: Metadata` - - `"failed"` + 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_call"` + 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 call. Always `image_generation_call`. + - `object: "thread.message"` - - `"image_generation_call"` + 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"` - - `CodeInterpreterCall object { id, code, container_id, 4 more }` + - `"assistant"` - A tool call to run code. + - `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 unique ID of the code interpreter tool call. + - `status: "in_progress" or "incomplete" or "completed"` - - `code: string` + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. - The code to run, or null if not available. + - `"in_progress"` - - `container_id: string` + - `"incomplete"` - The ID of the container used to run the code. + - `"completed"` - - `outputs: array of object { logs, type } or object { type, url }` + - `thread_id: string` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + The [thread](/docs/api-reference/threads) ID that this message belongs to. - - `Logs object { logs, type }` +- `first_id: string` - The logs output from the code interpreter. +- `has_more: boolean` - - `logs: string` +- `last_id: string` - The logs output from the code interpreter. +- `object: string` - - `type: "logs"` +### Example - The type of the output. Always `logs`. +```http +curl https://api.openai.com/v1/threads/$THREAD_ID/messages \ + -H 'OpenAI-Beta: assistants=v2' \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - - `"logs"` +#### Response - - `Image object { type, url }` +```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" +} +``` - The image output from the code interpreter. +### Example - - `type: "image"` +```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" +``` - The type of the output. Always `image`. +#### Response - - `"image"` +```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 +} +``` - - `url: string` +## Create message - The URL of the image output from the code interpreter. +**post** `/threads/{thread_id}/messages` - - `status: "in_progress" or "completed" or "incomplete" or 2 more` +Create a message. - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. +### Path Parameters - - `"in_progress"` +- `thread_id: string` - - `"completed"` +### Body Parameters - - `"incomplete"` +- `content: string or array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlockParam` - - `"interpreting"` + The text contents of the message. - - `"failed"` + - `TextContent = string` - - `type: "code_interpreter_call"` + The text contents of the message. - The type of the code interpreter tool call. Always `code_interpreter_call`. + - `ArrayOfContentParts = array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlockParam` - - `"code_interpreter_call"` + 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). - - `agent: optional object { agent_name }` + - `ImageFileContentBlock object { image_file, type }` - The agent that produced this item. + References an image [File](/docs/api-reference/files) in the content of a message. - - `agent_name: string` + - `image_file: ImageFile` - The canonical name of the agent that produced this item. + - `file_id: string` - - `LocalShellCall object { id, action, call_id, 3 more }` + 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 tool call to run a command on the local shell. + - `detail: optional "auto" or "low" or "high"` - - `id: 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 unique ID of the local shell call. + - `"auto"` - - `action: object { command, env, type, 3 more }` + - `"low"` - Execute a shell command on the server. + - `"high"` - - `command: array of string` + - `type: "image_file"` - The command to run. + Always `image_file`. - - `env: map[string]` + - `"image_file"` - Environment variables to set for the command. + - `ImageURLContentBlock object { image_url, type }` - - `type: "exec"` + References an image URL in the content of a message. - The type of the local shell action. Always `exec`. + - `image_url: ImageURL` - - `"exec"` + - `url: string` - - `timeout_ms: optional number` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - Optional timeout in milliseconds for the command. + - `detail: optional "auto" or "low" or "high"` - - `user: optional 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` - Optional user to run the command as. + - `"auto"` - - `working_directory: optional string` + - `"low"` - Optional working directory to run the command in. + - `"high"` - - `call_id: string` + - `type: "image_url"` - The unique ID of the local shell tool call generated by the model. + The type of the content part. - - `status: "in_progress" or "completed" or "incomplete"` + - `"image_url"` - The status of the local shell call. + - `TextContentBlockParam object { text, type }` - - `"in_progress"` + The text content that is part of a message. - - `"completed"` + - `text: string` - - `"incomplete"` + Text content to be sent to the model - - `type: "local_shell_call"` + - `type: "text"` - The type of the local shell call. Always `local_shell_call`. + Always `text`. - - `"local_shell_call"` + - `"text"` - - `agent: optional object { agent_name }` +- `role: "user" or "assistant"` - The agent that produced this item. + The role of the entity that is creating the message. Allowed values include: - - `agent_name: 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 canonical name of the agent that produced this item. + - `"user"` - - `LocalShellCallOutput object { id, output, type, 2 more }` + - `"assistant"` - The output of a local shell tool call. +- `attachments: optional array of object { file_id, tools }` - - `id: string` + A list of files attached to the message, and the tools they should be added to. - The unique ID of the local shell tool call generated by the model. + - `file_id: optional string` - - `output: string` + The ID of the file to attach to the message. - A JSON string of the output of the local shell tool call. + - `tools: optional array of CodeInterpreterTool or object { type }` - - `type: "local_shell_call_output"` + The tools to add this file to. - The type of the local shell tool call output. Always `local_shell_call_output`. + - `CodeInterpreterTool object { type }` - - `"local_shell_call_output"` + - `type: "code_interpreter"` - - `agent: optional object { agent_name }` + The type of tool being defined: `code_interpreter` - The agent that produced this item. + - `"code_interpreter"` - - `agent_name: string` + - `FileSearchTool object { type }` - The canonical name of the agent that produced this item. + - `type: "file_search"` - - `status: optional "in_progress" or "completed" or "incomplete"` + The type of tool being defined: `file_search` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `"file_search"` - - `"in_progress"` +- `metadata: optional Metadata` - - `"completed"` + 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. - - `"incomplete"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `ShellCall object { action, call_id, type, 5 more }` +### Returns - A tool representing a request to execute one or more shell commands. +- `Message object { id, assistant_id, attachments, 11 more }` - - `action: object { commands, max_output_length, timeout_ms }` + Represents a message within a [thread](/docs/api-reference/threads). - The shell commands and limits that describe how to run the tool call. + - `id: string` - - `commands: array of string` + The identifier, which can be referenced in API endpoints. - Ordered shell commands for the execution environment to run. + - `assistant_id: string` - - `max_output_length: optional number` + If applicable, the ID of the [assistant](/docs/api-reference/assistants) that authored this message. - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + - `attachments: array of object { file_id, tools }` - - `timeout_ms: optional number` + A list of files attached to the message, and the tools they were added to. - Maximum wall-clock time in milliseconds to allow the shell commands to run. + - `file_id: optional string` - - `call_id: string` + The ID of the file to attach to the message. - The unique ID of the shell tool call generated by the model. + - `tools: optional array of CodeInterpreterTool or object { type }` - - `type: "shell_call"` + The tools to add this file to. - The type of the item. Always `shell_call`. + - `CodeInterpreterTool object { type }` - - `"shell_call"` + - `type: "code_interpreter"` - - `id: optional string` + The type of tool being defined: `code_interpreter` - The unique ID of the shell tool call. Populated when this item is returned via API. + - `"code_interpreter"` - - `agent: optional object { agent_name }` + - `FileSearchTool object { type }` - The agent that produced this item. + - `type: "file_search"` - - `agent_name: string` + The type of tool being defined: `file_search` - The canonical name of the agent that produced this item. + - `"file_search"` - - `caller: optional object { type } or object { caller_id, type }` + - `completed_at: number` - The execution context that produced this tool call. + The Unix timestamp (in seconds) for when the message was completed. - - `Direct object { type }` + - `content: array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlock or RefusalContentBlock` - - `type: "direct"` + The content of the message in array of text and/or images. - The caller type. Always `direct`. + - `ImageFileContentBlock object { image_file, type }` - - `"direct"` + References an image [File](/docs/api-reference/files) in the content of a message. - - `Program object { caller_id, type }` + - `image_file: ImageFile` - - `caller_id: string` + - `file_id: string` - The call ID of the program item that produced this tool call. + 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. - - `type: "program"` + - `detail: optional "auto" or "low" or "high"` - The caller type. Always `program`. + 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`. - - `"program"` + - `"auto"` - - `environment: optional BetaLocalEnvironment or BetaContainerReference` + - `"low"` - The environment to execute the shell commands in. + - `"high"` - - `BetaLocalEnvironment object { type, skills }` + - `type: "image_file"` - - `BetaContainerReference object { container_id, type }` + Always `image_file`. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"image_file"` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `ImageURLContentBlock object { image_url, type }` - - `"in_progress"` + References an image URL in the content of a message. - - `"completed"` + - `image_url: ImageURL` - - `"incomplete"` + - `url: string` - - `ShellCallOutput object { call_id, output, type, 5 more }` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - The streamed output items emitted by a shell tool call. + - `detail: optional "auto" or "low" or "high"` - - `call_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` - The unique ID of the shell tool call generated by the model. + - `"auto"` - - `output: array of BetaResponseFunctionShellCallOutputContent` + - `"low"` - Captured chunks of stdout and stderr output, along with their associated outcomes. + - `"high"` - - `outcome: object { type } or object { exit_code, type }` + - `type: "image_url"` - The exit or timeout outcome associated with this shell call. + The type of the content part. - - `Timeout object { type }` + - `"image_url"` - Indicates that the shell call exceeded its configured time limit. + - `TextContentBlock object { text, type }` - - `type: "timeout"` + The text content that is part of a message. - The outcome type. Always `timeout`. + - `text: Text` - - `"timeout"` + - `annotations: array of FileCitationAnnotation or FilePathAnnotation` - - `Exit object { exit_code, type }` + - `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` - Indicates that the shell commands finished and returned an exit code. + 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. - - `exit_code: number` + - `end_index: number` - The exit code returned by the shell process. + - `file_citation: object { file_id }` - - `type: "exit"` + - `file_id: string` - The outcome type. Always `exit`. + The ID of the specific File the citation is from. - - `"exit"` + - `start_index: number` - - `stderr: string` + - `text: string` - Captured stderr output for the shell call. + The text in the message content that needs to be replaced. - - `stdout: string` + - `type: "file_citation"` - Captured stdout output for the shell call. + Always `file_citation`. - - `type: "shell_call_output"` + - `"file_citation"` - The type of the item. Always `shell_call_output`. + - `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` - - `"shell_call_output"` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `id: optional string` + - `end_index: number` - The unique ID of the shell tool call output. Populated when this item is returned via API. + - `file_path: object { file_id }` - - `agent: optional object { agent_name }` + - `file_id: string` - The agent that produced this item. + The ID of the file that was generated. - - `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_path"` - - `Direct object { type }` + Always `file_path`. - - `type: "direct"` + - `"file_path"` - The caller type. Always `direct`. + - `value: string` - - `"direct"` + The data that makes up the text. - - `Program object { caller_id, type }` + - `type: "text"` - - `caller_id: string` + Always `text`. - The call ID of the program item that produced this tool call. + - `"text"` - - `type: "program"` + - `RefusalContentBlock object { refusal, type }` - The caller type. Always `program`. + The refusal content generated by the assistant. - - `"program"` + - `refusal: string` - - `max_output_length: optional number` + - `type: "refusal"` - The maximum number of UTF-8 characters captured for this shell call's combined output. + Always `refusal`. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"refusal"` - The status of the shell call output. + - `created_at: number` - - `"in_progress"` + The Unix timestamp (in seconds) for when the message was created. - - `"completed"` + - `incomplete_at: number` - - `"incomplete"` + The Unix timestamp (in seconds) for when the message was marked as incomplete. - - `ApplyPatchCall object { call_id, operation, status, 4 more }` + - `incomplete_details: object { reason }` - A tool call representing a request to create, delete, or update files using diff patches. + On an incomplete message, details about why the message is incomplete. - - `call_id: string` + - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` - The unique ID of the apply patch tool call generated by the model. + The reason the message is incomplete. - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + - `"content_filter"` - The specific create, delete, or update instruction for the apply_patch tool call. + - `"max_tokens"` - - `CreateFile object { diff, path, type }` + - `"run_cancelled"` - Instruction for creating a new file via the apply_patch tool. + - `"run_expired"` - - `diff: string` + - `"run_failed"` - Unified diff content to apply when creating the file. + - `metadata: Metadata` - - `path: 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. - Path of the file to create relative to the workspace root. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `type: "create_file"` + - `object: "thread.message"` - The operation type. Always `create_file`. + The object type, which is always `thread.message`. - - `"create_file"` + - `"thread.message"` - - `DeleteFile object { path, type }` + - `role: "user" or "assistant"` - Instruction for deleting an existing file via the apply_patch tool. + The entity that produced the message. One of `user` or `assistant`. - - `path: string` + - `"user"` - Path of the file to delete relative to the workspace root. + - `"assistant"` - - `type: "delete_file"` + - `run_id: string` - The operation type. Always `delete_file`. + 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. - - `"delete_file"` + - `status: "in_progress" or "incomplete" or "completed"` - - `UpdateFile object { diff, path, type }` + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. - Instruction for updating an existing file via the apply_patch tool. + - `"in_progress"` - - `diff: string` + - `"incomplete"` - Unified diff content to apply to the existing file. + - `"completed"` - - `path: string` + - `thread_id: string` - Path of the file to update relative to the workspace root. + The [thread](/docs/api-reference/threads) ID that this message belongs to. - - `type: "update_file"` +### Example - The operation type. Always `update_file`. +```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" + }' +``` - - `"update_file"` +#### Response - - `status: "in_progress" or "completed"` +```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" +} +``` - The status of the apply patch tool call. One of `in_progress` or `completed`. +### Example - - `"in_progress"` +```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." + }' +``` - - `"completed"` +#### Response - - `type: "apply_patch_call"` +```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": {} +} +``` - The type of the item. Always `apply_patch_call`. +## Modify message - - `"apply_patch_call"` +**post** `/threads/{thread_id}/messages/{message_id}` - - `id: optional string` +Modifies a message. - The unique ID of the apply patch tool call. Populated when this item is returned via API. +### Path Parameters - - `agent: optional object { agent_name }` +- `thread_id: string` - The agent that produced this item. +- `message_id: string` - - `agent_name: string` +### Body Parameters - The canonical name of the agent that produced this item. +- `metadata: optional Metadata` - - `caller: optional object { type } or object { caller_id, 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. - The execution context that produced this tool call. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `Direct object { type }` +### Returns - - `type: "direct"` +- `Message object { id, assistant_id, attachments, 11 more }` - The caller type. Always `direct`. + Represents a message within a [thread](/docs/api-reference/threads). - - `"direct"` + - `id: string` - - `Program object { caller_id, type }` + The identifier, which can be referenced in API endpoints. - - `caller_id: string` + - `assistant_id: string` - The call ID of the program item that produced this tool call. + If applicable, the ID of the [assistant](/docs/api-reference/assistants) that authored this message. - - `type: "program"` + - `attachments: array of object { file_id, tools }` - The caller type. Always `program`. + A list of files attached to the message, and the tools they were added to. - - `"program"` + - `file_id: optional string` - - `ApplyPatchCallOutput object { call_id, status, type, 4 more }` + The ID of the file to attach to the message. - The streamed output emitted by an apply patch tool call. + - `tools: optional array of CodeInterpreterTool or object { type }` - - `call_id: string` + The tools to add this file to. - The unique ID of the apply patch tool call generated by the model. + - `CodeInterpreterTool object { type }` - - `status: "completed" or "failed"` + - `type: "code_interpreter"` - The status of the apply patch tool call output. One of `completed` or `failed`. + The type of tool being defined: `code_interpreter` - - `"completed"` + - `"code_interpreter"` - - `"failed"` + - `FileSearchTool object { type }` - - `type: "apply_patch_call_output"` + - `type: "file_search"` - The type of the item. Always `apply_patch_call_output`. + The type of tool being defined: `file_search` - - `"apply_patch_call_output"` + - `"file_search"` - - `id: optional string` + - `completed_at: number` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + The Unix timestamp (in seconds) for when the message was completed. - - `agent: optional object { agent_name }` + - `content: array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlock or RefusalContentBlock` - The agent that produced this item. + The content of the message in array of text and/or images. - - `agent_name: string` + - `ImageFileContentBlock object { image_file, type }` - The canonical name of the agent that produced this item. + References an image [File](/docs/api-reference/files) in the content of a message. - - `caller: optional object { type } or object { caller_id, type }` + - `image_file: ImageFile` - The execution context that produced this tool call. + - `file_id: string` - - `Direct object { 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. - - `type: "direct"` + - `detail: optional "auto" or "low" or "high"` - The caller type. Always `direct`. + 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`. - - `"direct"` + - `"auto"` - - `Program object { caller_id, type }` + - `"low"` - - `caller_id: string` + - `"high"` - The call ID of the program item that produced this tool call. + - `type: "image_file"` - - `type: "program"` + Always `image_file`. - The caller type. Always `program`. + - `"image_file"` - - `"program"` + - `ImageURLContentBlock object { image_url, type }` - - `output: optional string` + References an image URL in the content of a message. - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + - `image_url: ImageURL` - - `McpListTools object { id, server_label, tools, 3 more }` + - `url: string` - A list of tools available on an MCP server. + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `id: string` + - `detail: optional "auto" or "low" or "high"` - The unique ID of the list. + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - - `server_label: string` + - `"auto"` - The label of the MCP server. + - `"low"` - - `tools: array of object { input_schema, name, annotations, description }` + - `"high"` - The tools available on the server. + - `type: "image_url"` - - `input_schema: unknown` + The type of the content part. - The JSON schema describing the tool's input. + - `"image_url"` - - `name: string` + - `TextContentBlock object { text, type }` - The name of the tool. + The text content that is part of a message. - - `annotations: optional unknown` + - `text: Text` - Additional annotations about the tool. + - `annotations: array of FileCitationAnnotation or FilePathAnnotation` - - `description: optional string` + - `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` - The description of the tool. + 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: "mcp_list_tools"` + - `end_index: number` - The type of the item. Always `mcp_list_tools`. + - `file_citation: object { file_id }` - - `"mcp_list_tools"` + - `file_id: string` - - `agent: optional object { agent_name }` + The ID of the specific File the citation is from. - The agent that produced this item. + - `start_index: number` - - `agent_name: string` + - `text: string` - The canonical name of the agent that produced this item. + The text in the message content that needs to be replaced. - - `error: optional string` + - `type: "file_citation"` - Error message if the server could not list tools. + Always `file_citation`. - - `McpApprovalRequest object { id, arguments, name, 3 more }` + - `"file_citation"` - A request for human approval of a tool invocation. + - `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` - - `id: string` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - The unique ID of the approval request. + - `end_index: number` - - `arguments: string` + - `file_path: object { file_id }` - A JSON string of arguments for the tool. + - `file_id: string` - - `name: string` + The ID of the file that was generated. - The name of the tool to run. + - `start_index: number` - - `server_label: string` + - `text: string` - The label of the MCP server making the request. + The text in the message content that needs to be replaced. - - `type: "mcp_approval_request"` + - `type: "file_path"` - The type of the item. Always `mcp_approval_request`. + Always `file_path`. - - `"mcp_approval_request"` + - `"file_path"` - - `agent: optional object { agent_name }` + - `value: string` - The agent that produced this item. + The data that makes up the text. - - `agent_name: string` + - `type: "text"` - The canonical name of the agent that produced this item. + Always `text`. - - `McpApprovalResponse object { approval_request_id, approve, type, 3 more }` + - `"text"` - A response to an MCP approval request. + - `RefusalContentBlock object { refusal, type }` - - `approval_request_id: string` + The refusal content generated by the assistant. - The ID of the approval request being answered. + - `refusal: string` - - `approve: boolean` + - `type: "refusal"` - Whether the request was approved. + Always `refusal`. - - `type: "mcp_approval_response"` + - `"refusal"` - The type of the item. Always `mcp_approval_response`. + - `created_at: number` - - `"mcp_approval_response"` + The Unix timestamp (in seconds) for when the message was created. - - `id: optional string` + - `incomplete_at: number` - The unique ID of the approval response + 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. - - `reason: optional string` + - `"content_filter"` - Optional reason for the decision. + - `"max_tokens"` - - `McpCall object { id, arguments, name, 7 more }` + - `"run_cancelled"` - An invocation of a tool on an MCP server. + - `"run_expired"` - - `id: string` + - `"run_failed"` - The unique ID of the tool call. + - `metadata: Metadata` - - `arguments: 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. - A JSON string of the arguments passed to the tool. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `name: string` + - `object: "thread.message"` - The name of the tool that was run. + The object type, which is always `thread.message`. - - `server_label: string` + - `"thread.message"` - The label of the MCP server running the tool. + - `role: "user" or "assistant"` - - `type: "mcp_call"` + The entity that produced the message. One of `user` or `assistant`. - The type of the item. Always `mcp_call`. + - `"user"` - - `"mcp_call"` + - `"assistant"` - - `agent: optional object { agent_name }` + - `run_id: string` - The agent that produced this item. + 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. - - `agent_name: string` + - `status: "in_progress" or "incomplete" or "completed"` - The canonical name of the agent that produced this item. + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. - - `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. + - `"incomplete"` - - `error: optional string` + - `"completed"` - The error from the tool call, if any. + - `thread_id: string` - - `output: optional string` + The [thread](/docs/api-reference/threads) ID that this message belongs to. - The output from the tool call. +### Example - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` +```http +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 '{}' +``` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. +#### Response - - `"in_progress"` +```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" +} +``` - - `"completed"` +### Example - - `"incomplete"` +```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" \ + -d '{ + "metadata": { + "modified": "true", + "user": "abc123" + } + }' +``` - - `"calling"` +#### Response - - `"failed"` +```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": [] + } + } + ], + "file_ids": [], + "metadata": { + "modified": "true", + "user": "abc123" + } +} +``` - - `CustomToolCallOutput object { call_id, output, type, 3 more }` +## Retrieve message - The output of a custom tool call from your code, being sent back to the model. +**get** `/threads/{thread_id}/messages/{message_id}` - - `call_id: string` +Retrieve a message. - The call ID, used to map this custom tool call output to a custom tool call. +### Path Parameters - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` +- `thread_id: string` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. +- `message_id: string` - - `StringOutput = string` +### Returns - A string of the output of the custom tool call. +- `Message object { id, assistant_id, attachments, 11 more }` - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + Represents a message within a [thread](/docs/api-reference/threads). - Text, image, or file output of the custom tool call. + - `id: string` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + The identifier, which can be referenced in API endpoints. - A text input to the model. + - `assistant_id: string` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + If applicable, the ID of the [assistant](/docs/api-reference/assistants) that authored this message. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `attachments: array of object { file_id, tools }` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + A list of files attached to the message, and the tools they were added to. - A file input to the model. + - `file_id: optional string` - - `type: "custom_tool_call_output"` + The ID of the file to attach to the message. - The type of the custom tool call output. Always `custom_tool_call_output`. + - `tools: optional array of CodeInterpreterTool or object { type }` - - `"custom_tool_call_output"` + The tools to add this file to. - - `id: optional string` + - `CodeInterpreterTool object { type }` - The unique ID of the custom tool call output in the OpenAI platform. + - `type: "code_interpreter"` - - `agent: optional object { agent_name }` + The type of tool being defined: `code_interpreter` - The agent that produced this item. + - `"code_interpreter"` - - `agent_name: string` + - `FileSearchTool object { type }` - The canonical name of the agent that produced this item. + - `type: "file_search"` - - `caller: optional object { type } or object { caller_id, type }` + The type of tool being defined: `file_search` - The execution context that produced this tool call. + - `"file_search"` - - `Direct object { type }` + - `completed_at: number` - - `type: "direct"` + The Unix timestamp (in seconds) for when the message was completed. - The caller type. Always `direct`. + - `content: array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlock or RefusalContentBlock` - - `"direct"` + The content of the message in array of text and/or images. - - `Program object { caller_id, type }` + - `ImageFileContentBlock object { image_file, type }` - - `caller_id: string` + References an image [File](/docs/api-reference/files) in the content of a message. - The call ID of the program item that produced this tool call. + - `image_file: ImageFile` - - `type: "program"` + - `file_id: string` - The caller type. Always `program`. + 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. - - `"program"` + - `detail: optional "auto" or "low" or "high"` - - `CustomToolCall object { call_id, input, name, 5 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`. - A call to a custom tool created by the model. + - `"auto"` - - `call_id: string` + - `"low"` - An identifier used to map this custom tool call to a tool call output. + - `"high"` - - `input: string` + - `type: "image_file"` - The input for the custom tool call generated by the model. + Always `image_file`. - - `name: string` + - `"image_file"` - The name of the custom tool being called. + - `ImageURLContentBlock object { image_url, type }` - - `type: "custom_tool_call"` + References an image URL in the content of a message. - The type of the custom tool call. Always `custom_tool_call`. + - `image_url: ImageURL` - - `"custom_tool_call"` + - `url: string` - - `id: optional string` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - The unique ID of the custom tool call in the OpenAI platform. + - `detail: optional "auto" or "low" or "high"` - - `agent: optional object { agent_name }` + 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 agent that produced this item. + - `"auto"` - - `agent_name: string` + - `"low"` - The canonical name of the agent that produced this item. + - `"high"` - - `caller: optional object { type } or object { caller_id, type }` + - `type: "image_url"` - The execution context that produced this tool call. + The type of the content part. - - `Direct object { type }` + - `"image_url"` - - `type: "direct"` + - `TextContentBlock object { text, type }` - - `"direct"` + The text content that is part of a message. - - `Program object { caller_id, type }` + - `text: Text` - - `caller_id: string` + - `annotations: array of FileCitationAnnotation or FilePathAnnotation` - The call ID of the program item that produced this tool call. + - `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` - - `type: "program"` + 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. - - `"program"` + - `end_index: number` - - `namespace: optional string` + - `file_citation: object { file_id }` - The namespace of the custom tool being called. + - `file_id: string` - - `CompactionTrigger object { type, agent }` + The ID of the specific File the citation is from. - Compacts the current context. Must be the final input item. + - `start_index: number` - - `type: "compaction_trigger"` + - `text: string` - The type of the item. Always `compaction_trigger`. + The text in the message content that needs to be replaced. - - `"compaction_trigger"` + - `type: "file_citation"` - - `agent: optional object { agent_name }` + Always `file_citation`. - The agent that produced this item. + - `"file_citation"` - - `agent_name: string` + - `FilePathAnnotation object { end_index, file_path, start_index, 2 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. - - `ItemReference object { id, agent, type }` + - `end_index: number` - An internal identifier for an item to reference. + - `file_path: object { file_id }` - - `id: string` + - `file_id: string` - The ID of the item to reference. + The ID of the file that was generated. - - `agent: optional object { agent_name }` + - `start_index: number` - The agent that produced this item. + - `text: string` - - `agent_name: string` + The text in the message content that needs to be replaced. - The canonical name of the agent that produced this item. + - `type: "file_path"` - - `type: optional "item_reference"` + Always `file_path`. - The type of item to reference. Always `item_reference`. + - `"file_path"` - - `"item_reference"` + - `value: string` - - `Program object { id, call_id, code, 3 more }` + The data that makes up the text. - - `id: string` + - `type: "text"` - The unique ID of this program item. + Always `text`. - - `call_id: string` + - `"text"` - The stable call ID of the program item. + - `RefusalContentBlock object { refusal, type }` - - `code: string` + The refusal content generated by the assistant. - The JavaScript source executed by programmatic tool calling. + - `refusal: string` - - `fingerprint: string` + - `type: "refusal"` - Opaque program replay fingerprint that must be round-tripped. + Always `refusal`. - - `type: "program"` + - `"refusal"` - The item type. Always `program`. + - `created_at: number` - - `"program"` + The Unix timestamp (in seconds) for when the message was created. - - `agent: optional object { agent_name }` + - `incomplete_at: number` - The agent that produced this item. + The Unix timestamp (in seconds) for when the message was marked as incomplete. - - `agent_name: string` + - `incomplete_details: object { reason }` - The canonical name of the agent that produced this item. + On an incomplete message, details about why the message is incomplete. - - `ProgramOutput object { id, call_id, result, 3 more }` + - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` - - `id: string` + The reason the message is incomplete. - The unique ID of this program output item. + - `"content_filter"` - - `call_id: string` + - `"max_tokens"` - The call ID of the program item. + - `"run_cancelled"` - - `result: string` + - `"run_expired"` - The result produced by the program item. + - `"run_failed"` - - `status: "completed" or "incomplete"` + - `metadata: Metadata` - The terminal status of the program 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. - - `"completed"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `"incomplete"` + - `object: "thread.message"` - - `type: "program_output"` + The object type, which is always `thread.message`. - The item type. Always `program_output`. + - `"thread.message"` - - `"program_output"` + - `role: "user" or "assistant"` - - `agent: optional object { agent_name }` + The entity that produced the message. One of `user` or `assistant`. - The agent that produced this item. + - `"user"` - - `agent_name: string` + - `"assistant"` - The canonical name of the agent that produced this item. + - `run_id: string` -- `instructions: optional 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. - 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. + - `status: "in_progress" or "incomplete" or "completed"` -- `model: optional string` + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. - 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](https://platform.openai.com/docs/models) to browse and compare available models. + - `"in_progress"` -- `parallel_tool_calls: optional boolean` + - `"incomplete"` - Whether to allow the model to run tool calls in parallel. + - `"completed"` -- `personality: optional string or "friendly" or "pragmatic"` + - `thread_id: string` - 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 [thread](/docs/api-reference/threads) ID that this message belongs to. - - `string` +### Example - - `"friendly" or "pragmatic"` +```http +curl https://api.openai.com/v1/threads/$THREAD_ID/messages/$MESSAGE_ID \ + -H 'OpenAI-Beta: assistants=v2' \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - 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. +#### Response - - `"friendly"` +```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" +} +``` - - `"pragmatic"` +### Example -- `previous_response_id: optional string` +```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" +``` - The unique ID of the previous response to the model. Use this to create multi-turn conversations. Learn more about [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. +#### Response -- `reasoning: optional object { context, effort, generate_summary, 2 more }` +```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": {} +} +``` - **gpt-5 and o-series models only** Configuration options for [reasoning models](https://platform.openai.com/docs/guides/reasoning). +## Delete message - - `context: optional "auto" or "current_turn" or "all_turns"` +**delete** `/threads/{thread_id}/messages/{message_id}` - Controls which reasoning items are rendered back to the model on later turns. - When returned on a response, this is the effective reasoning context mode - used for the response. +Deletes a message. - - `"auto"` +### Path Parameters - - `"current_turn"` +- `thread_id: string` - - `"all_turns"` +- `message_id: string` - - `effort: optional "none" or "minimal" or "low" or 4 more` +### Returns - 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. +- `MessageDeleted object { id, deleted, object }` - - `"none"` + - `id: string` - - `"minimal"` + - `deleted: boolean` - - `"low"` + - `object: "thread.message.deleted"` - - `"medium"` + - `"thread.message.deleted"` - - `"high"` +### Example - - `"xhigh"` +```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" +``` - - `"max"` +#### Response - - `generate_summary: optional "auto" or "concise" or "detailed"` +```json +{ + "id": "id", + "deleted": true, + "object": "thread.message.deleted" +} +``` - **Deprecated:** use `summary` instead. +### Example - 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`. +```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" +``` - - `"auto"` +#### Response - - `"concise"` +```json +{ + "id": "msg_abc123", + "object": "thread.message.deleted", + "deleted": true +} +``` - - `"detailed"` +## Domain Types - - `mode: optional string or "standard" or "pro"` +### File Citation Annotation - Controls the reasoning execution mode for the request. +- `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` - When returned on a response, this is the effective execution mode. + 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. - - `string` + - `end_index: number` - - `"standard" or "pro"` + - `file_citation: object { file_id }` - Controls the reasoning execution mode for the request. + - `file_id: string` - When returned on a response, this is the effective execution mode. + The ID of the specific File the citation is from. - - `"standard"` + - `start_index: number` - - `"pro"` + - `text: string` - - `summary: optional "auto" or "concise" or "detailed"` + The text in the message content that needs to be replaced. - 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: "file_citation"` - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + Always `file_citation`. - - `"auto"` + - `"file_citation"` - - `"concise"` +### File Citation Delta Annotation - - `"detailed"` +- `FileCitationDeltaAnnotation object { index, type, end_index, 3 more }` -- `text: optional object { format, verbosity }` + 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. - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + - `index: number` - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + The index of the annotation in the text content part. - - `format: optional BetaResponseFormatTextConfig` + - `type: "file_citation"` - An object specifying the format that the model must output. + Always `file_citation`. - Configuring `{ "type": "json_schema" }` enables Structured Outputs, - which ensures the model will match your supplied JSON schema. Learn more in the - [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `"file_citation"` - The default format is `{ "type": "text" }` with no additional options. + - `end_index: optional number` - **Not recommended for gpt-4o and newer models:** + - `file_citation: optional object { file_id, quote }` - 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. + - `file_id: optional string` - - `Text object { type }` + The ID of the specific File the citation is from. - Default response format. Used to generate text responses. + - `quote: optional string` - - `type: "text"` + The specific quote in the file. - The type of response format being defined. Always `text`. + - `start_index: optional number` - - `"text"` + - `text: optional string` - - `BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` + The text in the message content that needs to be replaced. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). +### File Path Annotation - - `name: string` +- `FilePathAnnotation object { end_index, file_path, start_index, 2 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. + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `schema: map[unknown]` + - `end_index: number` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `file_path: object { file_id }` - - `type: "json_schema"` + - `file_id: string` - The type of response format being defined. Always `json_schema`. + The ID of the file that was generated. - - `"json_schema"` + - `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. - - `strict: optional boolean` + - `type: "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](https://platform.openai.com/docs/guides/structured-outputs). + Always `file_path`. - - `JSONObject object { type }` + - `"file_path"` - 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 Path Delta Annotation - - `type: "json_object"` +- `FilePathDeltaAnnotation object { index, type, end_index, 3 more }` - The type of response format being defined. Always `json_object`. + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `"json_object"` + - `index: number` - - `verbosity: optional "low" or "medium" or "high"` + The index of the annotation in the text content part. - 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`. + - `type: "file_path"` - - `"low"` + Always `file_path`. - - `"medium"` + - `"file_path"` - - `"high"` + - `end_index: optional number` -- `tool_choice: optional BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` + - `file_path: optional object { file_id }` - Controls which tool the model should use, if any. + - `file_id: optional string` - - `BetaToolChoiceOptions = "none" or "auto" or "required"` + The ID of the file that was generated. - Controls which (if any) tool is called by the model. + - `start_index: optional number` - `none` means the model will not call any tool and instead generates a message. + - `text: optional string` - `auto` means the model can pick between generating a message or calling one or - more tools. + The text in the message content that needs to be replaced. - `required` means the model must call one or more tools. +### Image File - - `"none"` +- `ImageFile object { file_id, detail }` - - `"auto"` + - `file_id: string` - - `"required"` + 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. - - `BetaToolChoiceAllowed object { mode, tools, type }` + - `detail: optional "auto" or "low" or "high"` - Constrains the tools available to the model to a pre-defined set. + 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`. - - `mode: "auto" or "required"` + - `"auto"` - Constrains the tools available to the model to a pre-defined set. + - `"low"` - `auto` allows the model to pick from among the allowed tools and generate a - message. + - `"high"` - `required` requires the model to call one or more of the allowed tools. +### Image File Content Block - - `"auto"` +- `ImageFileContentBlock object { image_file, type }` - - `"required"` + References an image [File](/docs/api-reference/files) in the content of a message. - - `tools: array of map[unknown]` + - `image_file: ImageFile` - A list of tool definitions that the model should be allowed to call. + - `file_id: string` - For the Responses API, the list of tool definitions might look like: + 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. - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + - `detail: optional "auto" or "low" or "high"` - - `type: "allowed_tools"` + 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`. - Allowed tool configuration type. Always `allowed_tools`. + - `"auto"` - - `"allowed_tools"` + - `"low"` - - `BetaToolChoiceTypes object { type }` + - `"high"` - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + - `type: "image_file"` - - `type: "file_search" or "web_search_preview" or "computer" or 5 more` + Always `image_file`. - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + - `"image_file"` - Allowed values are: +### Image File Delta - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` +- `ImageFileDelta object { detail, file_id }` - - `"file_search"` + - `detail: optional "auto" or "low" or "high"` - - `"web_search_preview"` + 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`. - - `"computer"` + - `"auto"` - - `"computer_use_preview"` + - `"low"` - - `"computer_use"` + - `"high"` - - `"web_search_preview_2025_03_11"` + - `file_id: optional string` - - `"image_generation"` + 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. - - `"code_interpreter"` +### Image File Delta Block - - `BetaToolChoiceFunction object { name, type }` +- `ImageFileDeltaBlock object { index, type, image_file }` - Use this option to force the model to call a specific function. + References an image [File](/docs/api-reference/files) in the content of a message. - - `name: string` + - `index: number` - The name of the function to call. + The index of the content part in the message. - - `type: "function"` + - `type: "image_file"` - For function calling, the type is always `function`. + Always `image_file`. - - `"function"` + - `"image_file"` - - `BetaToolChoiceMcp object { server_label, type, name }` + - `image_file: optional ImageFileDelta` - Use this option to force the model to call a specific tool on a remote MCP server. + - `detail: optional "auto" or "low" or "high"` - - `server_label: 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 label of the MCP server to use. + - `"auto"` - - `type: "mcp"` + - `"low"` - For MCP tools, the type is always `mcp`. + - `"high"` - - `"mcp"` + - `file_id: optional string` - - `name: optional 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. - The name of the tool to call on the server. +### Image URL - - `BetaToolChoiceCustom object { name, type }` +- `ImageURL object { url, detail }` - Use this option to force the model to call a specific custom tool. + - `url: string` - - `name: string` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - The name of the custom tool to call. + - `detail: optional "auto" or "low" or "high"` - - `type: "custom"` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - For custom tool calling, the type is always `custom`. + - `"auto"` - - `"custom"` + - `"low"` - - `BetaSpecificProgrammaticToolCallingParam object { type }` + - `"high"` - - `type: "programmatic_tool_calling"` +### Image URL Content Block - The tool to call. Always `programmatic_tool_calling`. +- `ImageURLContentBlock object { image_url, type }` - - `"programmatic_tool_calling"` + References an image URL in the content of a message. - - `BetaToolChoiceApplyPatch object { type }` + - `image_url: ImageURL` - Forces the model to call the apply_patch tool when executing a tool call. + - `url: string` - - `type: "apply_patch"` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - The tool to call. Always `apply_patch`. + - `detail: optional "auto" or "low" or "high"` - - `"apply_patch"` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - - `BetaToolChoiceShell object { type }` + - `"auto"` - Forces the model to call the shell tool when a tool call is required. + - `"low"` - - `type: "shell"` + - `"high"` - The tool to call. Always `shell`. + - `type: "image_url"` - - `"shell"` + The type of the content part. -- `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` + - `"image_url"` - 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. +### Image URL Delta - - `Function object { name, parameters, strict, 5 more }` +- `ImageURLDelta object { detail, 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). + - `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`. - The name of the function to call. + - `"auto"` - - `parameters: map[unknown]` + - `"low"` - A JSON schema object describing the parameters of the function. + - `"high"` - - `strict: boolean` + - `url: optional string` - Whether strict parameter validation is enforced for this function tool. + The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `type: "function"` +### Image URL Delta Block - The type of the function tool. Always `function`. +- `ImageURLDeltaBlock object { index, type, image_url }` - - `"function"` + References an image URL in the content of a message. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `index: number` - The tool invocation context(s). + The index of the content part in the message. - - `"direct"` + - `type: "image_url"` - - `"programmatic"` + Always `image_url`. - - `defer_loading: optional boolean` + - `"image_url"` - Whether this function is deferred and loaded via tool search. + - `image_url: optional ImageURLDelta` - - `description: optional string` + - `detail: optional "auto" or "low" or "high"` - A description of the function. Used by the model to determine whether or not to call the function. + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `output_schema: optional map[unknown]` + - `"auto"` - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `"low"` - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + - `"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). + - `url: optional string` - - `type: "file_search"` + The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - The type of the file search tool. Always `file_search`. +### Message - - `"file_search"` +- `Message object { id, assistant_id, attachments, 11 more }` - - `vector_store_ids: array of string` + Represents a message within a [thread](/docs/api-reference/threads). - The IDs of the vector stores to search. + - `id: string` - - `filters: optional object { key, type, value } or object { filters, type }` + The identifier, which can be referenced in API endpoints. - A filter to apply. + - `assistant_id: string` - - `ComparisonFilter object { key, type, value }` + If applicable, the ID of the [assistant](/docs/api-reference/assistants) that authored this message. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `attachments: array of object { file_id, tools }` - - `key: string` + A list of files attached to the message, and the tools they were added to. - The key to compare against the value. + - `file_id: optional string` - - `type: "eq" or "ne" or "gt" or 5 more` + The ID of the file to attach to the message. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `tools: optional array of CodeInterpreterTool or object { 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 tools to add this file to. - - `"eq"` + - `CodeInterpreterTool object { type }` - - `"ne"` + - `type: "code_interpreter"` - - `"gt"` + The type of tool being defined: `code_interpreter` - - `"gte"` + - `"code_interpreter"` - - `"lt"` + - `FileSearchTool object { type }` - - `"lte"` + - `type: "file_search"` - - `"in"` + The type of tool being defined: `file_search` - - `"nin"` + - `"file_search"` - - `value: string or number or boolean or array of string or number` + - `completed_at: number` - The value to compare against the attribute key; supports string, number, or boolean types. + The Unix timestamp (in seconds) for when the message was completed. - - `string` + - `content: array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlock or RefusalContentBlock` - - `number` + The content of the message in array of text and/or images. - - `boolean` + - `ImageFileContentBlock object { image_file, type }` - - `array of string or number` + References an image [File](/docs/api-reference/files) in the content of a message. - - `string` + - `image_file: ImageFile` - - `number` + - `file_id: string` - - `CompoundFilter object { filters, 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. - Combine multiple filters using `and` or `or`. + - `detail: optional "auto" or "low" or "high"` - - `filters: array of object { key, type, value } or unknown` + 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`. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `"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` + - `type: "image_file"` - The key to compare against the value. + Always `image_file`. - - `type: "eq" or "ne" or "gt" or 5 more` + - `"image_file"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `ImageURLContentBlock object { image_url, 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 + References an image URL in the content of a message. - - `"eq"` + - `image_url: ImageURL` - - `"ne"` + - `url: string` - - `"gt"` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `"gte"` + - `detail: optional "auto" or "low" or "high"` - - `"lt"` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - - `"lte"` + - `"auto"` - - `"in"` + - `"low"` - - `"nin"` + - `"high"` - - `value: string or number or boolean or array of string or number` + - `type: "image_url"` - The value to compare against the attribute key; supports string, number, or boolean types. + The type of the content part. - - `string` + - `"image_url"` - - `number` + - `TextContentBlock object { text, type }` - - `boolean` + The text content that is part of a message. - - `array of string or number` + - `text: Text` - - `string` + - `annotations: array of FileCitationAnnotation or FilePathAnnotation` - - `number` + - `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` - - `unknown` + 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: "and" or "or"` + - `end_index: number` - Type of operation: `and` or `or`. + - `file_citation: object { file_id }` - - `"and"` + - `file_id: string` - - `"or"` + The ID of the specific File the citation is from. - - `max_num_results: optional number` + - `start_index: number` - 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 text in the message content that needs to be replaced. - Ranking options for search. + - `type: "file_citation"` - - `hybrid_search: optional object { embedding_weight, text_weight }` + Always `file_citation`. - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `"file_citation"` - - `embedding_weight: number` + - `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` - The weight of the embedding in the reciprocal ranking fusion. + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `text_weight: number` + - `end_index: number` - The weight of the text in the reciprocal ranking fusion. + - `file_path: object { file_id }` - - `ranker: optional "auto" or "default-2024-11-15"` + - `file_id: string` - The ranker to use for the file search. + The ID of the file that was generated. - - `"auto"` + - `start_index: number` - - `"default-2024-11-15"` + - `text: string` - - `score_threshold: optional number` + The text in the message content that needs to be replaced. - 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: "file_path"` - - `Computer object { type }` + Always `file_path`. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `"file_path"` - - `type: "computer"` + - `value: string` - The type of the computer tool. Always `computer`. + The data that makes up the text. - - `"computer"` + - `type: "text"` - - `ComputerUsePreview object { display_height, display_width, environment, type }` + Always `text`. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `"text"` - - `display_height: number` + - `RefusalContentBlock object { refusal, type }` - The height of the computer display. + The refusal content generated by the assistant. - - `display_width: number` + - `refusal: string` - The width of the computer display. + - `type: "refusal"` - - `environment: "windows" or "mac" or "linux" or 2 more` + Always `refusal`. - The type of computer environment to control. + - `"refusal"` - - `"windows"` + - `created_at: number` - - `"mac"` + The Unix timestamp (in seconds) for when the message was created. - - `"linux"` + - `incomplete_at: number` - - `"ubuntu"` + The Unix timestamp (in seconds) for when the message was marked as incomplete. - - `"browser"` + - `incomplete_details: object { reason }` - - `type: "computer_use_preview"` + On an incomplete message, details about why the message is incomplete. - The type of the computer use tool. Always `computer_use_preview`. + - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` - - `"computer_use_preview"` + The reason the message is incomplete. - - `WebSearch object { type, filters, search_context_size, user_location }` + - `"content_filter"` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `"max_tokens"` - - `type: "web_search" or "web_search_2025_08_26"` + - `"run_cancelled"` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `"run_expired"` - - `"web_search"` + - `"run_failed"` - - `"web_search_2025_08_26"` + - `metadata: Metadata` - - `filters: optional object { allowed_domains }` + 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. - Filters for the search. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `allowed_domains: optional array of string` + - `object: "thread.message"` - 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.message`. - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `"thread.message"` - - `search_context_size: optional "low" or "medium" or "high"` + - `role: "user" or "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. + The entity that produced the message. One of `user` or `assistant`. - - `"low"` + - `"user"` - - `"medium"` + - `"assistant"` - - `"high"` + - `run_id: string` - - `user_location: optional object { city, country, region, 2 more }` + 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 approximate location of the user. + - `status: "in_progress" or "incomplete" or "completed"` - - `city: optional string` + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. - Free text input for the city of the user, e.g. `San Francisco`. + - `"in_progress"` - - `country: optional string` + - `"incomplete"` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `"completed"` - - `region: optional string` + - `thread_id: string` - Free text input for the region of the user, e.g. `California`. + The [thread](/docs/api-reference/threads) ID that this message belongs to. - - `timezone: optional string` +### Message Deleted - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. +- `MessageDeleted object { id, deleted, object }` - - `type: optional "approximate"` + - `id: string` - The type of location approximation. Always `approximate`. + - `deleted: boolean` - - `"approximate"` + - `object: "thread.message.deleted"` - - `Mcp object { server_label, type, allowed_callers, 9 more }` + - `"thread.message.deleted"` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). +### Message Delta - - `server_label: string` +- `MessageDelta object { content, role }` - A label for this MCP server, used to identify it in tool calls. + The delta containing the fields that have changed on the Message. - - `type: "mcp"` + - `content: optional array of ImageFileDeltaBlock or TextDeltaBlock or RefusalDeltaBlock or ImageURLDeltaBlock` - The type of the MCP tool. Always `mcp`. + The content of the message in array of text and/or images. - - `"mcp"` + - `ImageFileDeltaBlock object { index, type, image_file }` - - `allowed_callers: optional array of "direct" or "programmatic"` + References an image [File](/docs/api-reference/files) in the content of a message. - The tool invocation context(s). + - `index: number` - - `"direct"` + The index of the content part in the message. - - `"programmatic"` + - `type: "image_file"` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + Always `image_file`. - List of allowed tool names or a filter object. + - `"image_file"` - - `McpAllowedTools = array of string` + - `image_file: optional ImageFileDelta` - A string array of allowed tool names + - `detail: optional "auto" or "low" or "high"` - - `McpToolFilter object { read_only, tool_names }` + 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`. - A filter object to specify which tools are allowed. + - `"auto"` - - `read_only: optional boolean` + - `"low"` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `"high"` - - `tool_names: optional array of string` + - `file_id: optional string` - List of allowed tool names. + 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. - - `authorization: optional string` + - `TextDeltaBlock object { index, type, text }` - 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 content that is part of a message. - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + - `index: 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](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + The index of the content part in the message. - Currently supported `connector_id` values are: + - `type: "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` + Always `text`. - - `"connector_dropbox"` + - `"text"` - - `"connector_gmail"` + - `text: optional TextDelta` - - `"connector_googlecalendar"` + - `annotations: optional array of FileCitationDeltaAnnotation or FilePathDeltaAnnotation` - - `"connector_googledrive"` + - `FileCitationDeltaAnnotation object { index, type, end_index, 3 more }` - - `"connector_microsoftteams"` + 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. - - `"connector_outlookcalendar"` + - `index: number` - - `"connector_outlookemail"` + The index of the annotation in the text content part. - - `"connector_sharepoint"` + - `type: "file_citation"` - - `defer_loading: optional boolean` + Always `file_citation`. - Whether this MCP tool is deferred and discovered via tool search. + - `"file_citation"` - - `headers: optional map[string]` + - `end_index: optional number` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `file_citation: optional object { file_id, quote }` - - `require_approval: optional object { always, never } or "always" or "never"` + - `file_id: optional string` - Specify which of the MCP server's tools require approval. + The ID of the specific File the citation is from. - - `McpToolApprovalFilter object { always, never }` + - `quote: 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 specific quote in the file. - - `always: optional object { read_only, tool_names }` + - `start_index: optional number` - A filter object to specify which tools are allowed. + - `text: optional string` - - `read_only: optional boolean` + The text in the message content that needs to be replaced. - 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. + - `FilePathDeltaAnnotation object { index, type, end_index, 3 more }` - - `tool_names: optional array of string` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - List of allowed tool names. + - `index: number` - - `never: optional object { read_only, tool_names }` + The index of the annotation in the text content part. - A filter object to specify which tools are allowed. + - `type: "file_path"` - - `read_only: optional boolean` + Always `file_path`. - 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_path"` - - `tool_names: optional array of string` + - `end_index: optional number` - List of allowed tool names. + - `file_path: optional object { file_id }` - - `McpToolApprovalSetting = "always" or "never"` + - `file_id: optional string` - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + The ID of the file that was generated. - - `"always"` + - `start_index: optional number` - - `"never"` + - `text: optional 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. + - `value: optional string` - - `server_url: optional string` + The data that makes up the text. - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `RefusalDeltaBlock object { index, type, refusal }` - - `tunnel_id: optional string` + The refusal content that is part of a message. - 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. + - `index: number` - - `CodeInterpreter object { container, type, allowed_callers }` + The index of the refusal part in the message. - A tool that runs Python code to help generate a response to a prompt. + - `type: "refusal"` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + Always `refusal`. - 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. + - `"refusal"` - - `string` + - `refusal: optional string` - The container ID. + - `ImageURLDeltaBlock object { index, type, image_url }` - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + References an image URL in the content of a message. - 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 content part in the message. - Always `auto`. + - `type: "image_url"` - - `"auto"` + Always `image_url`. - - `file_ids: optional array of string` + - `"image_url"` - An optional list of uploaded files to make available to your code. + - `image_url: optional ImageURLDelta` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `detail: optional "auto" or "low" or "high"` - The memory limit for the code interpreter container. + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `"1g"` + - `"auto"` - - `"4g"` + - `"low"` - - `"16g"` + - `"high"` - - `"64g"` + - `url: optional string` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - Network access policy for the container. + - `role: optional "user" or "assistant"` - - `BetaContainerNetworkPolicyDisabled object { type }` + The entity that produced the message. One of `user` or `assistant`. - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `"user"` - - `type: "code_interpreter"` + - `"assistant"` - The type of the code interpreter tool. Always `code_interpreter`. +### Message Delta Event - - `"code_interpreter"` +- `MessageDeltaEvent object { id, delta, object }` - - `allowed_callers: optional array of "direct" or "programmatic"` + Represents a message delta i.e. any changed fields on a message during streaming. - The tool invocation context(s). + - `id: string` - - `"direct"` + The identifier of the message, which can be referenced in API endpoints. - - `"programmatic"` + - `delta: MessageDelta` - - `ProgrammaticToolCalling object { type }` + The delta containing the fields that have changed on the Message. - - `type: "programmatic_tool_calling"` + - `content: optional array of ImageFileDeltaBlock or TextDeltaBlock or RefusalDeltaBlock or ImageURLDeltaBlock` - The type of the tool. Always `programmatic_tool_calling`. + The content of the message in array of text and/or images. - - `"programmatic_tool_calling"` + - `ImageFileDeltaBlock object { index, type, image_file }` - - `ImageGeneration object { type, action, background, 9 more }` + References an image [File](/docs/api-reference/files) in the content of a message. - A tool that generates images using the GPT image models. + - `index: number` - - `type: "image_generation"` + The index of the content part in the message. - The type of the image generation tool. Always `image_generation`. + - `type: "image_file"` - - `"image_generation"` + Always `image_file`. - - `action: optional "generate" or "edit" or "auto"` + - `"image_file"` - Whether to generate a new image or edit an existing image. Default: `auto`. + - `image_file: optional ImageFileDelta` - - `"generate"` + - `detail: optional "auto" or "low" or "high"` - - `"edit"` + 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"` - - `background: optional "transparent" or "opaque" or "auto"` + - `"low"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + - `"high"` - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + - `file_id: optional string` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + 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. - - `"transparent"` + - `TextDeltaBlock object { index, type, text }` - - `"opaque"` + The text content that is part of a message. - - `"auto"` + - `index: number` - - `input_fidelity: optional "high" or "low"` + The index of the content part in the 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`. + - `type: "text"` - - `"high"` + Always `text`. - - `"low"` + - `"text"` - - `input_image_mask: optional object { file_id, image_url }` + - `text: optional TextDelta` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `annotations: optional array of FileCitationDeltaAnnotation or FilePathDeltaAnnotation` - - `file_id: optional string` + - `FileCitationDeltaAnnotation object { index, type, end_index, 3 more }` - File ID for the mask 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_url: optional string` + - `index: number` - Base64-encoded mask image. + The index of the annotation in the text content part. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `type: "file_citation"` - The image generation model to use. Default: `gpt-image-1`. + Always `file_citation`. - - `string` + - `"file_citation"` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `end_index: optional number` - The image generation model to use. Default: `gpt-image-1`. + - `file_citation: optional object { file_id, quote }` - - `"gpt-image-1"` + - `file_id: optional string` - - `"gpt-image-1-mini"` + The ID of the specific File the citation is from. - - `"gpt-image-2"` + - `quote: optional string` - - `"gpt-image-2-2026-04-21"` + The specific quote in the file. - - `"gpt-image-1.5"` + - `start_index: optional number` - - `"chatgpt-image-latest"` + - `text: optional string` - - `moderation: optional "auto" or "low"` + The text in the message content that needs to be replaced. - Moderation level for the generated image. Default: `auto`. + - `FilePathDeltaAnnotation object { index, type, end_index, 3 more }` - - `"auto"` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `"low"` + - `index: number` - - `output_compression: optional number` + The index of the annotation in the text content part. - Compression level for the output image. Default: 100. + - `type: "file_path"` - - `output_format: optional "png" or "webp" or "jpeg"` + Always `file_path`. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `"file_path"` - - `"png"` + - `end_index: optional number` - - `"webp"` + - `file_path: optional object { file_id }` - - `"jpeg"` + - `file_id: optional string` - - `partial_images: optional number` + The ID of the file that was generated. - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `start_index: optional number` - - `quality: optional "low" or "medium" or "high" or "auto"` + - `text: optional string` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + The text in the message content that needs to be replaced. - - `"low"` + - `value: optional string` - - `"medium"` + The data that makes up the text. - - `"high"` + - `RefusalDeltaBlock object { index, type, refusal }` - - `"auto"` + The refusal content that is part of a message. - - `size: optional string or "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 refusal part in the message. - - `string` + - `type: "refusal"` - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + Always `refusal`. - 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`. + - `"refusal"` - - `"1024x1024"` + - `refusal: optional string` - - `"1024x1536"` + - `ImageURLDeltaBlock object { index, type, image_url }` - - `"1536x1024"` + References an image URL in the content of a message. - - `"auto"` + - `index: number` - - `LocalShell object { type }` + The index of the content part in the message. - A tool that allows the model to execute shell commands in a local environment. + - `type: "image_url"` - - `type: "local_shell"` + Always `image_url`. - The type of the local shell tool. Always `local_shell`. + - `"image_url"` - - `"local_shell"` + - `image_url: optional ImageURLDelta` - - `Shell object { type, allowed_callers, environment }` + - `detail: optional "auto" or "low" or "high"` - A tool that allows the model to execute shell commands. + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `type: "shell"` + - `"auto"` - The type of the shell tool. Always `shell`. + - `"low"` - - `"shell"` + - `"high"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `url: optional string` - The tool invocation context(s). + The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `"direct"` + - `role: optional "user" or "assistant"` - - `"programmatic"` + The entity that produced the message. One of `user` or `assistant`. - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + - `"user"` - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `"assistant"` - - `BetaLocalEnvironment object { type, skills }` + - `object: "thread.message.delta"` - - `BetaContainerReference object { container_id, type }` + The object type, which is always `thread.message.delta`. - - `Custom object { name, type, allowed_callers, 3 more }` + - `"thread.message.delta"` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) +### Refusal Content Block - - `name: string` +- `RefusalContentBlock object { refusal, type }` - The name of the custom tool, used to identify it in tool calls. + The refusal content generated by the assistant. - - `type: "custom"` + - `refusal: string` - The type of the custom tool. Always `custom`. + - `type: "refusal"` - - `"custom"` + Always `refusal`. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"refusal"` - The tool invocation context(s). +### Refusal Delta Block - - `"direct"` +- `RefusalDeltaBlock object { index, type, refusal }` - - `"programmatic"` + The refusal content that is part of a message. - - `defer_loading: optional boolean` + - `index: number` - Whether this tool should be deferred and discovered via tool search. + The index of the refusal part in the message. - - `description: optional string` + - `type: "refusal"` - Optional description of the custom tool, used to provide more context. + Always `refusal`. - - `format: optional object { type } or object { definition, syntax, type }` + - `"refusal"` - The input format for the custom tool. Default is unconstrained text. + - `refusal: optional string` - - `Text object { type }` +### Text - Unconstrained free-form text. +- `Text object { annotations, value }` - - `type: "text"` + - `annotations: array of FileCitationAnnotation or FilePathAnnotation` - Unconstrained text format. Always `text`. + - `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` - - `"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. - - `Grammar object { definition, syntax, type }` + - `end_index: number` - A grammar defined by the user. + - `file_citation: object { file_id }` - - `definition: string` + - `file_id: string` - The grammar definition. + The ID of the specific File the citation is from. - - `syntax: "lark" or "regex"` + - `start_index: number` - The syntax of the grammar definition. One of `lark` or `regex`. + - `text: string` - - `"lark"` + The text in the message content that needs to be replaced. - - `"regex"` + - `type: "file_citation"` - - `type: "grammar"` + Always `file_citation`. - Grammar format. Always `grammar`. + - `"file_citation"` - - `"grammar"` + - `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` - - `Namespace object { description, name, tools, type }` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - Groups function/custom tools under a shared namespace. + - `end_index: number` - - `description: string` + - `file_path: object { file_id }` - A description of the namespace shown to the model. + - `file_id: string` - - `name: string` + The ID of the file that was generated. - The namespace name used in tool calls (for example, `crm`). + - `start_index: number` - - `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. + The text in the message content that needs to be replaced. - - `Function object { name, type, allowed_callers, 5 more }` + - `type: "file_path"` - - `name: string` + Always `file_path`. - - `type: "function"` + - `"file_path"` - - `"function"` + - `value: string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The data that makes up the text. - The tool invocation context(s). +### Text Content Block - - `"direct"` +- `TextContentBlock object { text, type }` - - `"programmatic"` + The text content that is part of a message. - - `defer_loading: optional boolean` + - `text: Text` - Whether this function should be deferred and discovered via tool search. + - `annotations: array of FileCitationAnnotation or FilePathAnnotation` - - `description: optional string` + - `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` - - `output_schema: optional map[unknown]` + 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. - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `end_index: number` - - `parameters: optional unknown` + - `file_citation: object { file_id }` - - `strict: optional boolean` + - `file_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 specific File the citation is from. - - `Custom object { name, type, allowed_callers, 3 more }` + - `start_index: number` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `text: string` - - `name: string` + The text in the message content that needs to be replaced. - The name of the custom tool, used to identify it in tool calls. + - `type: "file_citation"` - - `type: "custom"` + Always `file_citation`. - The type of the custom tool. Always `custom`. + - `"file_citation"` - - `"custom"` + - `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` - - `allowed_callers: optional array of "direct" or "programmatic"` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - The tool invocation context(s). + - `end_index: number` - - `"direct"` + - `file_path: object { file_id }` - - `"programmatic"` + - `file_id: string` - - `defer_loading: optional boolean` + The ID of the file that was generated. - Whether this tool should be deferred and discovered via tool search. + - `start_index: number` - - `description: optional string` + - `text: string` - Optional description of the custom tool, used to provide more context. + The text in the message content that needs to be replaced. - - `format: optional object { type } or object { definition, syntax, type }` + - `type: "file_path"` - The input format for the custom tool. Default is unconstrained text. + Always `file_path`. - - `Text object { type }` + - `"file_path"` - Unconstrained free-form text. + - `value: string` + + The data that makes up the text. - `type: "text"` - Unconstrained text format. Always `text`. + Always `text`. - `"text"` - - `Grammar object { definition, syntax, type }` +### Text Content Block Param - A grammar defined by the user. +- `TextContentBlockParam object { text, type }` - - `definition: string` + The text content that is part of a message. - The grammar definition. + - `text: string` - - `syntax: "lark" or "regex"` + Text content to be sent to the model - The syntax of the grammar definition. One of `lark` or `regex`. + - `type: "text"` - - `"lark"` + Always `text`. - - `"regex"` + - `"text"` - - `type: "grammar"` +### Text Delta - Grammar format. Always `grammar`. +- `TextDelta object { annotations, value }` - - `"grammar"` + - `annotations: optional array of FileCitationDeltaAnnotation or FilePathDeltaAnnotation` - - `type: "namespace"` + - `FileCitationDeltaAnnotation object { index, type, end_index, 3 more }` - The type of the tool. Always `namespace`. + 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. - - `"namespace"` + - `index: number` - - `ToolSearch object { type, description, execution, parameters }` + The index of the annotation in the text content part. - Hosted or BYOT tool search configuration for deferred tools. + - `type: "file_citation"` - - `type: "tool_search"` + Always `file_citation`. - The type of the tool. Always `tool_search`. + - `"file_citation"` - - `"tool_search"` + - `end_index: optional number` - - `description: optional string` + - `file_citation: optional object { file_id, quote }` - Description shown to the model for a client-executed tool search tool. + - `file_id: optional string` - - `execution: optional "server" or "client"` + The ID of the specific File the citation is from. - Whether tool search is executed by the server or by the client. + - `quote: optional string` - - `"server"` + The specific quote in the file. - - `"client"` + - `start_index: optional number` - - `parameters: optional unknown` + - `text: optional string` - Parameter schema for a client-executed tool search tool. + The text in the message content that needs to be replaced. - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + - `FilePathDeltaAnnotation object { index, type, end_index, 3 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 URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a 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 annotation in the text content part. - - `"web_search_preview"` + - `type: "file_path"` - - `"web_search_preview_2025_03_11"` + Always `file_path`. - - `search_content_types: optional array of "text" or "image"` + - `"file_path"` - - `"text"` + - `end_index: optional number` - - `"image"` + - `file_path: optional object { file_id }` - - `search_context_size: optional "low" or "medium" or "high"` + - `file_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 file that was generated. - - `"low"` + - `start_index: optional number` - - `"medium"` + - `text: optional string` - - `"high"` + The text in the message content that needs to be replaced. - - `user_location: optional object { type, city, country, 2 more }` + - `value: optional string` - The user's location. + The data that makes up the text. - - `type: "approximate"` +### Text Delta Block - The type of location approximation. Always `approximate`. +- `TextDeltaBlock object { index, type, text }` - - `"approximate"` + The text content that is part of a message. - - `city: optional string` + - `index: number` - Free text input for the city of the user, e.g. `San Francisco`. + The index of the content part in the message. - - `country: optional string` + - `type: "text"` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + Always `text`. - - `region: optional string` + - `"text"` - Free text input for the region of the user, e.g. `California`. + - `text: optional TextDelta` - - `timezone: optional string` + - `annotations: optional array of FileCitationDeltaAnnotation or FilePathDeltaAnnotation` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `FileCitationDeltaAnnotation object { index, type, end_index, 3 more }` - - `ApplyPatch object { type, allowed_callers }` + 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. - Allows the assistant to create, delete, or update files using unified diffs. + - `index: number` - - `type: "apply_patch"` + The index of the annotation in the text content part. - The type of the tool. Always `apply_patch`. + - `type: "file_citation"` - - `"apply_patch"` + Always `file_citation`. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"file_citation"` - The tool invocation context(s). + - `end_index: optional number` - - `"direct"` + - `file_citation: optional object { file_id, quote }` - - `"programmatic"` + - `file_id: optional string` -- `truncation: optional "auto" or "disabled"` + The ID of the specific File the citation is from. - 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. + - `quote: optional string` - - `"auto"` + The specific quote in the file. - - `"disabled"` + - `start_index: optional number` -### Returns + - `text: optional string` -- `input_tokens: number` + The text in the message content that needs to be replaced. -- `object: "response.input_tokens"` + - `FilePathDeltaAnnotation object { index, type, end_index, 3 more }` - - `"response.input_tokens"` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. -### Example + - `index: number` -```http -curl https://api.openai.com/v1/responses/input_tokens \ - -X POST \ - -H 'OpenAI-Beta: assistants=v2' \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + The index of the annotation in the text content part. -#### Response + - `type: "file_path"` -```json -{ - "input_tokens": 123, - "object": "response.input_tokens" -} -``` + Always `file_path`. -### Example + - `"file_path"` -```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." - }' -``` + - `end_index: optional number` -#### Response + - `file_path: optional object { file_id }` -```json -{ - "object": "response.input_tokens", - "input_tokens": 11 -} -``` + - `file_id: optional string` -## Domain Types + The ID of the file that was generated. -### Input Token Count Response + - `start_index: optional number` -- `InputTokenCountResponse object { input_tokens, object }` + - `text: optional string` - - `input_tokens: number` + The text in the message content that needs to be replaced. - - `object: "response.input_tokens"` + - `value: optional string` - - `"response.input_tokens"` + The data that makes up the text.